You build an MCP server, wire it up to a local inspector or Claude Desktop, and it just works. Then you point a production agent at it — Claude Code running in CI, an autonomous loop, whatever — and it falls over. No clean error, usually. Just a hang, a truncated response, or the agent calling the same tool five times in a row and getting nowhere.

I've hit versions of all four of the failures below while wiring MCP servers into agent workflows. None of them show up in local testing, because local testing quietly gives you things production doesn't: a shared process, a tiny dataset, one obvious tool to call, and your own shell's credentials sitting right there in the environment.

1. Your stdout is corrupting the protocol stream

Local dev leans on stdio transport — the client spawns your server as a child process and pipes stdin/stdout directly. It's simple, and it's also fragile in a way that doesn't announce itself until something else is on the other end.

Here's the failure: any console.log() or print() statement in your tool code writes straight into the same stream carrying JSON-RPC messages. Locally, with one client and one server on the same box, you might get lucky and never trip over it. In a distributed setup — client in one container, server in another — that stdout pollution causes deserialization errors that don't look like your bug at all. They look like the agent randomly losing the plot mid-conversation.

The fix has two parts. First, redirect every log statement to stderr or a proper file logger (Pino, Winston, whatever you're already using) — never let application logs touch stdout in stdio mode. Second, if the client and server aren't running on the same machine, stop using stdio entirely. Move to SSE over HTTPS with an explicit reconnect buffer, and add heartbeat ping/pong frames so a dropped connection gets detected before the agent's own tool-call timeout fires and blames the wrong layer.

2. You're shipping 50KB of JSON into a context window built for 500 tokens

This one's sneaky because it doesn't fail loudly — it fails by degrading everything around it.

Local tests usually run against a mock dataset with five or ten records. A tool like list_customer_records or fetch_database_schema returns a small, clean payload and you move on. In production, that same tool call against a real database can return thousands of rows as raw, uncompressed JSON. That payload doesn't just cost you tokens — it saturates the model's active context window, which means earlier system instructions or conversation state can get silently pushed out. Best case, you get a context_length_exceeded error. Worse case, the agent just starts behaving inconsistently and you spend an afternoon debugging the wrong thing.

Three changes fix this at the source, not the symptom:

That last one matters most. Don't trust the caller to ask nicely for a small page — truncate at the boundary so a bad query can't blow the budget no matter what the agent requests.

3. The agent can't tell your tools apart

If you've named your tools get_data, query_db, and search_info, you've built an ambiguity problem, not a tool catalog. A human skimming your docs might figure out which one to use from context. An LLM agent choosing at inference time, with no memory of your internal reasoning, often can't — and when it guesses wrong, it doesn't just fail once. It retries, guesses again, and can burn through a token budget in a loop that never converges on the right call.

Treat tool descriptions as prompt engineering, because that's what they are. Specify exact preconditions, required parameters, and what the return type actually looks like — don't leave it implied. Where two tools genuinely overlap, merge them or rename them around the actual domain: search_postgresql_users and fetch_stripe_billing_summary leave a lot less room for a wrong guess than query_db and get_data do. And use strict JSON schema typing with real enums for string parameters instead of accepting a loose key-value map — the tighter the schema, the fewer ways there are to call it wrong.

4. Auth that works because your shell is doing it for you

This is the one that hangs instead of erroring, which makes it the most frustrating to debug cold.

Locally, your MCP server inherits your active shell's environment: API keys, OAuth tokens, whatever's already exported. If a tool needs interactive authorization — an OAuth consent screen, a CLI confirmation — that flow just works, because you're a human sitting at a terminal who can respond to a prompt. An autonomous agent running in a non-interactive session can't. The server ends up blocking on stdin input that will never arrive, and the session just hangs until the host client eventually times out and kills it.

Don't let the server discover missing credentials at call time — validate them at startup and throw an immediate protocol error if something's missing, rather than blocking silently three tool calls later. Inject API keys and refresh tokens as environment variables at container startup so there's nothing left to prompt for. And it's worth adding a dedicated check_auth_status tool the agent can call proactively, so it can verify connectivity before attempting a protected operation instead of finding out the hard way.

The pattern underneath all four

Every one of these bugs exists because local dev gives you a shortcut production doesn't: a shared process instead of a network boundary, a tiny dataset instead of a real one, one obvious tool instead of a dozen similarly-named ones, your own credentials instead of none. None of that is a coincidence — it's just what "it works on my machine" always means. If you're about to ship an MCP server, run through these four before an agent finds them for you in production.