Part 4 of the Things I Didn't Know About Claude series.
This one is about MCP debugging. I was doing it wrong.
The Quiz That Caught Me
"What's the best first step to test if your MCP tools work?"
My answer: connect it to Claude Desktop and try it. The correct answer: use MCP Inspector.
npx @modelcontextprotocol/inspector — a debug UI that connects to your MCP server, lists all tools, lets you call them individually, and shows the raw JSON-RPC messages. For Python servers, the SDK has a built-in equivalent: mcp dev mcpserver.py.
I'd been debugging MCP tools by connecting them to Claude and seeing what happened. That's like testing a REST API by building the entire frontend first. Inspector lets you isolate and test each tool independently — see the input schema, send test requests, read the responses — before any client integration.
The course showed Inspector running on port 6277 with a clean UI: Resources, Prompts, Tools tabs at the top. Click Connect, click List Tools, pick a tool, fill in the arguments, hit Run. That's it. No Claude needed.
How Clients Actually Discover Tools
The second thing I missed was the protocol itself. I knew MCP servers expose tools. I didn't know the mechanism.
The flow:
-
initialize— handshake between client and server -
ListToolsRequest— the client asks "what can you do?" -
CallToolRequest— the client invokes a specific tool
ListToolsRequest returns each tool's name, description, and input schema as JSON. That's how Claude knows what tools are available and what parameters they accept. It's not magic. It's not hardcoded. It's a protocol message.
This changed how I think about MCP server design. The descriptions in your ListToolsRequest responses are what Claude reads to decide when and how to use each tool. Bad descriptions mean Claude misusing your tools. Good descriptions mean Claude picks the right tool at the right time.
The Python SDK Makes This Easy
In the Python SDK, you define tools with a @mcp.tool decorator and Field(description=...) for arguments. The SDK auto-generates the JSON schema — no hand-writing schemas. The function's return value becomes the tool_result sent back to the client. Errors are just raise ValueError(...).
The key insight: your tool function's docstring and Field descriptions are what show up in ListToolsRequest. They're not just documentation. They're the instructions Claude reads.
Why This Matters
If you're building MCP servers, the development lifecycle is: write code → test with Inspector → fix issues → integrate with a client. Skipping the Inspector step means debugging your server through Claude's interpretation of your tools — an unnecessary layer of indirection.
Next in the series: Workflows aren't agents, and why the distinction changes how you build things.
Anthropic Academy is free: anthropic.skilljar.com
Related:
Is your Claude Code setup actually safe? Run npx cc-health-check — a free 20-point diagnostic. Score below 80? The Claude Code Ops Kit fixes everything in one command.
Have you used MCP Inspector? Or do you debug MCP tools the hard way too?
Top comments (0)