How to Design Better MCP Servers for AI Agents

TL;DR

Design MCP servers as curated products for agents, not as automatic wrappers around REST APIs. Effective designs reduce discovery costs, minimize slow and context-heavy iteration, and expose only the information and actions needed for a task. Because AI agents have limited context and imperfect reasoning, smaller, purpose-built interfaces can produce better outcomes than broad collections of API endpoints.

Transcript

I really do appreciate that you're all here. I'm going to try and make this as painless as possible. We're not going to do an interactive part. We're going to talk through stuff. I'm happy to go off script. I'm happy to take questions if there's stuff we want to explore at any moment in this. My goal is I'd like to share with you a lot of things th... Read More

Key Insights

• MCP servers are interfaces for agents, so they should be designed around agent strengths, weaknesses, and use cases. Treating them as ordinary API mirrors ignores the same product-design considerations that shape websites, SDKs, clients, and mobile applications for human users.
• Humans rarely use raw APIs directly because they generally rely on products and developer interfaces placed between themselves and the underlying endpoints. The claim that an AI should use any API a human can use overlooks both this mediation and the fallibility of current agents.
• Discovery is relatively cheap for human developers because they can inspect documentation once, select the routes they need, and retain that understanding throughout development. For agents, discovery can recur whenever they connect and enumerate every available tool and description, consuming tokens repeatedly.
• Iteration is relatively cheap for human developers because they can write a script that calls selected routes rapidly and rerun it when necessary. Agent iteration is slower, and every additional call may resend the preceding interaction history, subject to the system's caching configuration.
• Context is limited for language-model agents because their working memory is bounded by the tokens supplied to them and whatever information is represented in their model weights. MCP interfaces must therefore avoid filling that limited context with irrelevant tools, descriptions, and intermediate results.
• An agent can search a large collection of information, but it may need to inspect many irrelevant items before identifying what matters. This needle-in-a-haystack intuition explains why broad tool catalogs can waste tokens and increase the opportunity for confusion or poor tool selection.
• Curation is the central responsibility of an MCP developer because a large body of API information must be reduced into an interface appropriate for agents. A smaller, purpose-specific surface helps constrain discovery, reduce iteration, and preserve context for the task itself.
• MCP provides a standard, controllable way to communicate information and actions to agents, but server quality remains constrained by client implementations. Some clients do not fully follow the specification, so developers must build the best possible servers while recognizing those practical limitations.

Questions & Answers

Q: How should an MCP server be designed for AI agents?

An MCP server should be designed as a curated product for agents rather than as a direct copy of an existing REST API. Its tools, descriptions, and actions should reflect agent limitations in discovery, iteration, and context. The goal is to expose a small, relevant surface that helps the agent complete intended tasks without inspecting unnecessary endpoints or making avoidable calls.

Q: Why are REST API wrappers often poor MCP servers?

REST API wrappers often reproduce interfaces created for SDKs and human developers rather than for agents. A generated wrapper may expose every endpoint and description, forcing the agent to discover and evaluate a large surface. That process consumes tokens, adds confusion, and can encourage unnecessary iteration. A useful MCP server instead curates capabilities around the agent's actual tasks.

Q: Why is tool discovery expensive for AI agents?

Tool discovery is expensive because an agent can enumerate every tool and description when it connects to an MCP server. Unlike a human developer who may inspect API documentation once and reuse that understanding, the agent can repeat discovery whenever it starts. A large server therefore spends limited tokens describing capabilities before the agent performs the requested work.

Q: How does agent iteration differ from human API development?

Human developers can inspect documentation, choose a few routes, write a script, and execute those calls quickly. If the result fails, they can rerun the script. Agent iteration is slower because each additional call creates another reasoning and communication step. Depending on caching, later calls may also send the complete history of earlier calls, increasing context and token costs.

Q: Why does limited context matter when building MCP tools?

A language-model agent works with a bounded context containing the tokens it has received, along with information embedded in its model weights. Irrelevant tool definitions, verbose descriptions, and repeated call history compete with task-specific information inside that context. MCP designers should therefore limit exposed material and preserve the agent's working capacity for reasoning and completing the requested task.

Q: What does curation mean in MCP server design?

Curation means selecting and shaping a focused subset of information and actions from a potentially large underlying API or system. The MCP developer decides what an agent genuinely needs, how capabilities should be described, and which operations should be combined or omitted. This reduces discovery overhead, limits unnecessary iteration, and keeps irrelevant material out of the agent's constrained context.

Q: Why should agents have interfaces built specifically for them?

Agents deserve dedicated interfaces for the same reason humans use websites, SDKs, clients, and mobile applications instead of raw APIs. Interfaces translate underlying systems into forms suited to their users. Because agents are powerful but fallible, and because they face distinct costs in discovery, iteration, and context, their interfaces should be optimized for those characteristics rather than inherited unchanged.

Q: What role does MCP play in agent-native product design?

MCP supplies a standard method for presenting information and actions to agents, while allowing server developers to control how capabilities are discovered and used. That standard creates an opportunity to build agent-specific products instead of generic API mirrors. Results still depend partly on client behavior, and some current clients may not fully comply with the MCP specification.

Summary & Key Takeaways

• MCP servers should be treated as products built specifically for AI agents. Simply converting every REST endpoint into a tool preserves an interface originally intended for developers and SDKs. A stronger design curates available information and actions, accounting for how agents discover tools, make repeated calls, and manage limited context.

• Discovery has different economics for humans and agents. A developer can inspect documentation once, identify a few relevant routes, and reuse that knowledge throughout an application. An agent may enumerate the server's tools and descriptions whenever it starts, so a large surface area repeatedly consumes tokens before useful work even begins.

• Iteration is slower and more expensive for agents because each additional call can include the history of previous calls, depending on the caching setup. MCP designers should therefore reduce unnecessary steps and provide focused capabilities. The central principle is curation: expose a small, task-appropriate interface that accommodates agent limitations and improves outcomes.