Your MCP server passes manual tests and fails in agents

You built a Model Context Protocol server, called every tool by hand, and each one worked. Then you wired it into an agent that chains five calls to finish a task, and the task fails more often than it succeeds. The server is not broken in the way you tested. It is unreliable in the way agents actually use it, and that gap is where most MCP projects stall.

The short answer, for anyone skimming:

• Per-call reliability that looks fine in isolation compounds badly across a chain. Five calls at 71 percent each succeed end-to-end only about 18 percent of the time.
• Most failures fall into five classes, and four of them are fixable by the server author.
• The ecosystem is young: in one audit of 1,847 servers, 52 percent were abandoned and only 17 percent met a reasonable production bar.
• The fix is boring engineering, typed schemas, explicit timeouts, quota handling, and one of the reference SDKs, not a rewrite.

Why a 71 percent tool is a broken tool

Agents do not call one tool. They plan, call, read the result, and call again. Reliability multiplies across that chain. A tool that succeeds 71 percent of the time, which feels acceptable in a demo, gives you 0.71 to the fifth power, roughly 18 percent, across a five-step task. Ten steps drops it near 3 percent. The reliability bar an agent needs per call is closer to 95 to 99 percent, not 71.

This is the same compounding math that makes long agent runs collapse for reasons unrelated to the model, which we covered in how reasoning models collapse over long agent chains. The model can be perfect and the run still fails because a tool in the middle returned a malformed payload or timed out. Your MCP server is one of those multiplicands, so its individual reliability sets a ceiling on everything built on top of it.

The five failure modes, by frequency

Stress testing across many production servers sorts failures into a consistent distribution. Knowing the order tells you where to spend the first day.

Schema mismatches, about 38 percent

The single largest class. The tool advertises one shape and returns another, or accepts loosely typed input the model fills in wrong. The model passes a string where a number is expected, omits a field the server silently requires, or gets back a structure that does not match the declared output. The fix is a typed schema enforced at the boundary, with validation that rejects bad input clearly instead of half-processing it. Tight, well-described schemas also help the model call the tool correctly in the first place, which is the theme of our guide to designing tools for production AI agents.

Timeouts, about 24 percent

The tool calls a slow upstream and hangs with no deadline, so the agent stalls or the transport gives up mid-call. The fix is an explicit per-tool timeout plus cancellation support, so a slow call fails fast with a clear error the agent can react to, rather than freezing the whole run.

Auth and quota errors, about 19 percent

Tokens expire, rate limits hit, and the server surfaces a raw 401 or 429 that the agent cannot interpret. The fix is per-tool quota tracking and graceful handling of 429s, returning a structured, retryable error with a hint about when to retry. Auth belongs in this layer too; our note on MCP authentication and security covers doing it without leaking credentials into tool output.

Upstream API failures, about 12 percent

The dependency the tool wraps is down or returns an error. You cannot fix the upstream, but you can stop it from looking like a server bug: catch the error, return a typed failure the agent can route around, and avoid retrying a non-idempotent call blindly.

MCP protocol bugs, about 7 percent

The smallest class, and the most self-inflicted. Hand-rolled protocol handling drifts from the spec. The fix is the cheapest of all: use one of the reference SDK implementations instead of writing the wire protocol yourself. If you are starting fresh, our MCP server tutorial walks through building on an SDK from the start.

Add those up and four of the five classes, everything except the upstream being genuinely down, are fixable by the server author. That is good news. Reliability here is an engineering problem with known fixes, not an open research question.

The ecosystem is younger than the hype

It helps to be realistic about what you are building on. In an audit of 1,847 MCP servers, 52 percent were effectively abandoned, 31 percent were lightly maintained, and only 17 percent met a reasonable production bar. The median server had 6 commits in its lifetime and was last touched 142 days ago. If you are pulling a third-party MCP server into a product, treat it like any other dependency with a thin maintenance record: read the code, pin the version, and wrap it with your own timeout and error handling. Do not assume the reliability work was done for you.

How to make a server agent-ready

The work is mechanical, and it pays off across every agent that touches the server.

Make every output typed and validated

Declare input and output schemas, validate both, and fail loudly on mismatch. This alone removes the largest failure class. Describe each field well enough that the model knows what to put there.

Put a deadline on every call

No tool should be able to hang forever. Set a per-tool timeout, support cancellation, and return a clear timeout error so the agent can retry or choose another path.

Return errors the agent can act on

A good error says what went wrong and whether retrying will help. Map 429s and transient upstream failures to retryable errors with backoff hints; map bad input to non-retryable validation errors. The agent can only recover from failures it can understand.

Measure reliability per tool, not per demo

Track success rate, latency, and error class for each tool in production. You cannot improve a number you do not watch, and per-tool data tells you which tool is dragging down a whole chain. This is the tooling side of the broader point in agent observability versus evals: you need both the live signal and the offline test set.

Frequently asked questions

Why does my MCP server work in manual tests but fail inside an agent?

Manual tests call one tool at a time and you read each result yourself. Agents chain calls, and per-call reliability multiplies, so a tool that passes 71 percent of the time alone can sink a five-step task to roughly 18 percent. The server is not newly broken; the chain just exposes its real reliability.

What is the most common MCP server failure?

Schema mismatches, around 38 percent of failures in stress tests, where the tool returns a shape that does not match what it declared or accepts input the model fills in incorrectly. Enforcing a typed schema at the boundary removes most of them.

How reliable does each tool need to be?

Aim for 95 to 99 percent per call. Because reliability compounds across an agent's chain of calls, anything lower makes multi-step tasks fail often even when every individual tool looks acceptable in isolation.

Should I write the MCP protocol myself?

No. Protocol bugs are the smallest failure class precisely because the fix is to use one of the reference SDK implementations. Hand-rolling the wire format adds risk for no benefit; spend that time on schemas, timeouts, and error handling instead.