You ship an MCP server, and the model still calls the wrong tool. Or it calls the right one with a malformed argument, gets a stack trace back, retries the same way, and burns 40k tokens before giving up. Meanwhile your `list_records` tool returns a 12,000-token JSON blob for a question that needed three fields. The 2026 reality is that MCP server tool design — not the protocol, not the SDK — is what separates a server an agent uses correctly from one it thrashes against. FastMCP made standing up a server trivial; it did nothing to stop you from exposing 40 thin CRUD wrappers that read like a database schema instead of a task list. The failure mode is quiet: no errors in your logs, just an agent that quietly performs worse with your server attached than without it.
This is for developers who build and maintain MCP servers — backend and platform engineers wrapping internal APIs, tool authors publishing to registries, and anyone whose agent integration works in the demo and degrades in production. Assumes you write Python or TypeScript comfortably, understand HTTP and JSON Schema, and have at minimum read the MCP spec or shipped a toy server. It is not an introduction to LLMs, prompt engineering for chat, or agent framework selection. It does not cover writing MCP clients, and it is not a tour of the SDK changelog.
Being straight with you about where AI helps here: models are genuinely good at generating boilerplate server scaffolding, drafting JSON Schemas from a type definition, and writing the mechanical parts of a transport layer. They are bad — reliably, expensively bad — at judging tool granularity, because that judgment requires knowing which workflows your users actually run and which sequences of calls the model will attempt under ambiguity. They will also happily write a tool description that reads well to you and parses badly to another model. Every boundary decision, every error message intended to trigger self-correction, and every auth and scoping choice needs human review. A tool that lets an agent delete production data because the schema permitted it is not a model failure; it’s a design failure you signed off on.
What This Guide Covers
- How to decide tool boundaries so a handful of task-shaped tools outperform dozens of thin endpoint wrappers — with the reasoning you can apply to your own domain, not just a rule of thumb
- Writing tool descriptions and input schemas the model reads as operating instructions, so it picks correctly on the first attempt instead of probing
- Return-shape patterns that cut token spend hard: pagination, truncation envelopes, and resource links that defer payload until it’s actually needed
- Structured output and output schemas that let downstream code trust what comes back without defensive parsing
- Error design that turns a failed call into a corrected retry — what the model needs in the message to fix itself, and what noise makes it worse
- Progressive disclosure using resources, prompts, and tool filtering so a large surface area doesn’t flood the context window
- Human-in-the-loop mechanics — elicitation, sampling, and progress reporting — for operations that shouldn’t run unattended
- A clear-eyed comparison of stdio versus Streamable HTTP, and how the choice constrains your deployment and scaling story
- OAuth 2.1 resource-server authentication and the security hardening steps that separate an internal prototype from something you expose
- Building an eval harness that measures tool selection accuracy and argument correctness, so design changes are verified rather than vibed
- Parallel Python and TypeScript FastMCP 2.x implementations, so you can follow along in the stack you actually ship
- A complete worked build of a production server, end to end, showing how the individual decisions compose under real constraints
- Registry publishing, versioning, and deprecation practices for servers other teams depend on
- The failure patterns worth recognizing early — the ones that look fine in testing and surface as degraded agent behavior in production
Instant online access the moment checkout completes — you’ll be reading within a minute. One purchase, the complete guide, no upsell and no add-on tier waiting behind it.
Reviews
There are no reviews yet.