Here's a scene we've seen more than once. A server has 40 passing tests, a clean Inspector run and a green CI badge. Then a user types "pull last month's invoices for Acme" into Claude Desktop. The model calls search_customers when it should call list_invoices, passes "last month" as an ISO date, gets back Invalid input, and apologises its way out of the conversation. No test failed, because no test ever had a model in it.

Search for MCP server development tools and you'll mostly find lists of SDKs: TypeScript, Python, FastMCP, and official SDKs for Java, Kotlin, C#, Go and others. Any of them will register a tool and return JSON in an afternoon. So pick one in ten minutes and put the rest of your tooling budget into feedback loops. Below are the four layers where a working server gets misused, in the order you'll hit them.

The SDK is the smallest decision

Use the official SDK for the language you already deploy. The TypeScript SDK takes Zod schemas. The Python SDK, and FastMCP built on it, turns type hints and Pydantic models into JSON Schema. Both handle the initialize handshake, capability negotiation and transports, so nobody on your team should be writing JSON-RPC frames by hand. If you add a second runtime to production because one SDK demoed better, you'll be paying for it in dependency upgrades and on-call knowledge for as long as the server runs.

The decision that actually matters inside the SDK is how strict your schemas are. query: string plus options: object leaves the model guessing. status: enum["open","paid","void"], a required customer_id, format: date and a one-line description per field cost nothing, and they cut out whole classes of bad calls before they're made. If you're starting from zero, our walkthrough on building an MCP server covers the skeleton. This piece is about everything after it compiles.

MCP Inspector is the first tool you open

npx @modelcontextprotocol/inspector connects to your server over stdio or HTTP and shows you exactly what a client receives: the tool list, the generated schemas, resources, prompts and raw responses. It catches the schema that came out differently from what you wrote. A Pydantic field with a default that you meant to be required. A docstring that never reached description. A Union that turned into an anyOf the model will struggle with. It's a debugger that checks one call at a time. It isn't a regression suite.

It also shows you the stdio bug before your users find it. Under stdio, stdout belongs to the protocol. A single leftover print("here") or console.log(result) puts non-JSON bytes into the stream, the client fails to parse the frame, and you get a disconnect with no useful message. Send all logging to stderr on day one and add a lint rule that rejects stdout writes in server code. This is the most common reason a server that connected yesterday doesn't connect today.

Tests that run without a model

Both major SDKs let you run client and server in one process. In TypeScript that's InMemoryTransport.createLinkedPair(). In Python it's the SDK's in-memory session helper, or FastMCP's Client(server). Every call goes through real serialization and real schema validation, with zero tokens and no network. Most of your coverage belongs here: an empty result set, the last page of pagination, an upstream 504, an expired token, a 403 on a single record, and the exact text the model sees in each of those cases.

Test error strings as carefully as results, because the model reads them and decides what to do next. Given Invalid input, it either retries the same bad call or gives up. Given date must be YYYY-MM-DD; received 'next Tuesday', it fixes the argument and succeeds on the second call. Payload size gets the same treatment. A tool that returns 200 full records when the user needed five summaries fills context on every call, and our MCP token cost benchmark shows how quickly that grows. Put a byte ceiling on each tool's response and fail the build when it's crossed.

Evals that run with one

Most teams skip this layer, and it's the only one that tells you whether the server actually works. An eval is a file of realistic requests, each paired with the tool calls you expect, run against a real model connected to your server. For each request you score three things: did it pick the right tool, were the arguments valid and sensible, and did it recover after an error. Twenty prompts will catch more than a hundred unit tests, as long as they include vague phrasing, multi-step requests and at least three that should trigger no tool at all.

Evals find the bugs that code review can't. Two tools, get_order and find_orders, whose descriptions overlap enough that the model flips between them. A parameter called id that gets filled with a customer email. A tool that never gets called because its description is a single word. The fix is almost always a rewrite of the description, not of the code, and the MCP server best practices we follow are mostly about making tools models can tell apart. Rerun the full set on every description change, because the rewrite that fixes get_order can break find_orders.

What breaks between the Inspector and the client

When a server works in the Inspector and fails in Claude Desktop, the environment is usually to blame, not the code. Desktop clients spawn your server as a subprocess without your shell profile, so a node installed through nvm or a python from pyenv isn't on PATH, and you get spawn node ENOENT. Put absolute binary paths in the client config, pass secrets through its env block, and on macOS read ~/Library/Logs/Claude/mcp*.log before you change any code. Remote servers on Streamable HTTP add two new failure points: OAuth flows that redirect somewhere the client can't follow, and reverse proxies that buffer the stream until it times out.

Once the server is reachable over HTTP, security tooling becomes part of the build. That means tokens scoped per tool, validation on every argument, and treating tool output as untrusted input the moment it re-enters a model's context, since a fetched document can carry instructions. Our MCP server security checklist is what we run before anything ships. If you'd rather have the whole loop built and maintained by a team that has already debugged these failures, that's what our MCP server development work covers.

Questions, answered.

What tools do I need to develop an MCP server?

Four things: an official MCP SDK in the language you already deploy, the MCP Inspector for checking schemas and responses one call at a time, an in-memory test harness for protocol-level tests, and a small eval set run against a real model. Only the eval set tells you whether the model picks the right tool with the right arguments.

Is FastMCP better than the official Python MCP SDK?

FastMCP is a higher-level layer on the official SDK. Tool definitions are shorter, and it ships an in-memory client, Client(server), that makes tests easy to write. Either is fine. The choice matters far less than strict schemas and tool descriptions the model can tell apart.

How do I debug an MCP server that won't connect?

Run it in the MCP Inspector first to confirm the server works on its own. If it does, check for anything writing to stdout, since that corrupts stdio transport, and make sure the client config uses absolute binary paths, because desktop clients don't inherit your shell PATH. Then read the client's MCP logs, which on macOS live at ~/Library/Logs/Claude/mcp*.log for Claude Desktop.

How do I test an MCP server without calling an LLM?

Connect a client to your server in-process. In TypeScript use InMemoryTransport.createLinkedPair(); in Python use the SDK's in-memory session helper or FastMCP's Client(server). Calls go through real serialization and schema validation, so you can assert on results, error text and payload size quickly and without spending any tokens.

Which MCP transport should I use, stdio or HTTP?

Use stdio for local servers that a desktop client launches as a subprocess. Use Streamable HTTP for remote or shared servers, and budget time for OAuth redirects and for reverse proxies that buffer streamed responses. Those two cause most HTTP-only failures.