# Your MCP Server is Bad (and you should feel bad)

Jeremiah Lowin, Prefect | AI Engineer CODE 2025 | 54:33

Source: https://www.youtube.com/watch?v=96G7FLab8xc
Channel: AI Engineer (https://www.youtube.com/@aiDotEngineer). Summarised by AIE Talks.
Page: https://aietalks.com/talks/your-mcp-server-is-bad-and-you-should-feel-bad
Published: 2026-01-12
Tags: context-engineering, mcp, tool-use

## TL;DR
- MCP servers need an agent-focused interface because agents pay discovery costs repeatedly, iterate slowly, and have limited context.
- A good server exposes outcomes through focused tools instead of asking an agent to combine many low-level API operations.
- The practical design rules are to flatten arguments, write useful instructions and errors, respect the token budget, and curate the server down to its essentials.

## Summary
Jeremiah Lowin argues that an MCP server should be designed like a product for an agent, rather than generated mechanically from a REST API. Humans discover an API once, then run deterministic code quickly. Agents repeatedly enumerate tools, spend tokens on descriptions, send prior history with later calls, and work within a limited context window. Lowin proposes designing around discovery, iteration, and context. The server should expose outcomes such as checking an order status, with the underlying API calls hidden inside one agent-facing tool. Tool names and arguments should be written for agent selection, complex arguments should be flattened, and errors should explain how to recover. He also recommends limiting the tools visible to an agent, using read-only annotations, and treating REST conversion as a bootstrap technique rather than a production design.

## Key ideas
### MCP servers need an interface designed for agents
[03:28](https://www.youtube.com/watch?v=96G7FLab8xc&t=208s)
Lowin says an MCP server is an interface for an agent, so it should be designed around an agent's strengths and limits. Humans usually discover an API once by reading documentation or using Swagger. Agents repeat discovery whenever they connect, enumerating every tool and description and spending tokens each time. Humans can run a sequence of API calls quickly and cheaply, while agents iterate slowly because each call can send the previous conversation history again. Their context is also limited to what the model currently remembers. Lowin reduces these differences to discovery, iteration, and context. An agent can find a needle in a haystack, but it will inspect every piece of hay first.

### Expose outcomes instead of atomic API operations
[14:36](https://www.youtube.com/watch?v=96G7FLab8xc&t=876s)
Lowin's example server exposes separate operations for finding a user, listing orders, filtering them, and checking a status. That is straightforward for a human-written REST client, but it forces an agent to choose the order, understand argument formats, and make at least three round trips. His recommendation is to start with the outcome. A tool such as "track latest order and give an email" makes the intended result clear, while the server performs the known sequence internally. He calls this one tool equals one agent story. The underlying API calls still happen, but the agent does not spend time acting as an expensive, slow, stochastic orchestrator when ordinary code can perform the workflow.

### Tool names and arguments should help the agent choose correctly
[16:36](https://www.youtube.com/watch?v=96G7FLab8xc&t=996s)
Lowin says tool names should be chosen for the agent that selects them, rather than for future developers who might think in REST endpoints. Arguments deserve the same treatment. He recommends replacing a configuration dictionary with top-level primitives such as email, include_cancelled, and status. Literal values or enums are preferable when the choices are constrained. He also warns against tightly coupled arguments, where the valid values for one field depend on another field. Structured arguments are harder for models and clients to handle, and he describes a case where Cloud Desktop sent object arguments as strings. FastMCP added deserialization behavior for this client, although Lowin says he dislikes needing that workaround.

### Instructions, examples, and errors all become agent context
[21:52](https://www.youtube.com/watch?v=96G7FLab8xc&t=1312s)
A server without instructions makes the agent guess how to use it, and those guesses become part of the history. Lowin recommends documenting the server and every tool, with examples used carefully. Examples behave like contracts in practice: when an example contains two tags, he repeatedly saw the model produce two tags even when asked for at least ten. Errors also become prompts. A bare Python exception, empty value error, or numeric error code gives the agent little useful information. A detailed error can explain how to recover from a common failure and provide information only when it is needed. The message should remain clear, since an overly aggressive error can make the agent avoid the tool permanently.

### Token budget limits how much functionality an agent can use
[27:22](https://www.youtube.com/watch?v=96G7FLab8xc&t=1642s)
Tool descriptions consume context during the initial handshake, and the agent may connect to several servers. Lowin describes a company with 800 endpoints and argues that even a small amount of schema and documentation per tool could consume the entire context window, leaving no room for useful work. He says the budget should be treated as scarce and that authors should be parsimonious when they do not know the exact limit. Progressive disclosure can reduce the initial payload, but client behavior matters. Cloud Desktop, in his example, hashes tools into a SQLite database on first contact and ignores some protocol-compliant ways to provide more information later. If the author controls the client, more tailored strategies become possible.

### A large tool count is a warning to curate or split the server
[35:24](https://www.youtube.com/watch?v=96G7FLab8xc&t=2124s)
Lowin uses 50 tools visible to an agent as a rough point where performance problems begin. He does not call every larger server bad, since the GitHub server has about 170 tools and its team has worked on semantic routing. Still, a large count is a smell. It may indicate that admin and user tools should be separated, that tools should be namespaced, or that multiple servers would be easier for an agent to use. He points to Fiverr's experience, where Kelly Kفل first expanded a server to roughly 188 tools and later reduced it to five. Lowin presents that sequence as the difference between making a system work and making it work well.

### REST conversion is useful for starting, but should not reach production unchanged
[38:27](https://www.youtube.com/watch?v=96G7FLab8xc&t=2307s)
Lowin takes responsibility for FastMCP's popular REST-to-MCP conversion feature, while telling users not to ship the generated result unchanged. A REST wrapper is a fast way to test whether an agent can use a couple of endpoints and to solve one problem before adding new code. After that initial experiment, the author should hide the endpoint sequence behind an agent-facing outcome and curate the information exposed to the model. Converting every endpoint reproduces the REST API's operations, descriptions, and argument structure. That creates the discovery, iteration, and context problems discussed throughout the talk. His advice is to bootstrap with generated tools, then remove the wrapper-like design before production.

### An MCP server is a user interface for an agent
[41:42](https://www.youtube.com/watch?v=96G7FLab8xc&t=2502s)
Lowin closes by saying that an MCP server is a user interface, not merely a tool collection or transport layer. His working rules are to focus on outcomes, flatten arguments, treat instructions as context, respect the token budget, and curate ruthlessly. He admits that even experienced MCP developers add too many tools while experimenting because they are unsure which one an agent will use. Normal API practice encourages keeping versions and adding compatible capabilities, but that instinct can make an agent-facing interface harder to use. He compares excessive MCP exposure to showing a REST API directly to a human. The server should be reduced to the smallest surface that supports the intended workflows.

## Notable quotes
- "An MCP server is nothing but an interface to that problem and or solution." (09:00)
- "The most important word in the universe for MCP developers is curate." (09:20)
- "Errors are prompts." (24:39)
- "Just don't end up ship the REST API to prod as an MCP server. You will regret it. You will pay for it." (39:37)
- "You are not building a tool. You are building a user interface and treat it like a user interface because it is the interface that your agent is going to use." (42:11)

## Tools & references mentioned
- Prefect Technologies
- Apache Airflow
- Marvin
- FastMCP
- MCP
- David from Anthropic
- Block
- GitHub
- Cloud Desktop
- Claude Code
- ChatGPT
- SEP 1686
- Fiverr
- Kelly Kفل
- Cloudflare
- Anthropic

## Who should watch
- You have generated an MCP server from an OpenAPI or REST specification and need to decide what should remain before production.
- Your agent spends too many tokens discovering tools or makes repeated calls to complete workflows that your code already understands.
- You build MCP clients or frameworks and need to account for inconsistent client support, context limits, permissions, and progressive disclosure.

## Related talks

- [Bending a Public MCP Server Without Breaking It](https://aietalks.com/talks/bending-a-public-mcp-server-without-breaking-it) (Nimrod Hauser, Baz, 40:50)
- [MCP Is Not Good Yet](https://aietalks.com/talks/mcp-is-not-good-yet) (David Cramer, Sentry, 16:41)
- [Just do it. (let your tools think for themselves)](https://aietalks.com/talks/just-do-it-let-your-tools-think-for-themselves) (Robert Chandler, Wordware, 06:50)
- [Are MCPs Overhyped? A Rant about MCPs](https://aietalks.com/talks/are-mcps-overhyped-a-rant-about-mcps) (Henry Mao, Smithery, 07:29)
- [MCP = Mega Context Problem](https://aietalks.com/talks/mcp-mega-context-problem) (Matt Carey, Cloudflare, 22:42)