Five MCP Integration Mistakes That Fail Somewhere Else

Most MCP integration bugs do not fail where they are made. A log line written by the server ends the session one layer down, in the client's transport. A business rule that throws ends up as a JSON-RPC error that the model may never be shown. A tool catalog generated from an OpenAPI file costs you on every model turn, and nothing anywhere reports it as a failure. The cost lands on someone else's side of the protocol, usually later, and usually as a timeout.

This article goes through five of them. Each one is reproduced against the official Java SDK and paired with its fix, and every measurement below is output from one recorded run. The demo is at michalwolinski/mcp-integration-mistakes-java. It has a small order-management server in several variants, plus a scenario runner that plays the MCP client: it launches each variant as a stdio subprocess, prints what the client actually received, and checks every outcome against the claim made here, exiting non-zero if any of them stops holding. The stack is JDK 27 (Temurin 27+35) and io.modelcontextprotocol.sdk:mcp 2.1.0, the current stable release, which negotiates protocol revision 2025-11-25. All of it runs in Docker, with images pinned by digest.

Two neighbouring topics have their own articles. Protocol security (tool poisoning, scopes, step-up authorization) is covered in agent guardrails and permissions, and what the stateless 2026-07-28 revision changes inside a handler is covered in the PHP MCP server article. This one is about wiring: how a correct server reaches the model, and the five places where that path breaks without telling you. Each rule cited here reads the same in 2025-11-25 and in 2026-07-28. Where the newer revision adds something relevant, I say so.

1. A log line on stdout

On the stdio transport, the server's standard output is the protocol. The stdio binding spells it out: the server "MUST NOT write anything to its stdout that is not a valid MCP message", and it "MAY write UTF-8 strings to stderr for any logging purposes". In Java, the usual way to break that rule is a logging configuration that looks harmless. A Logback ConsoleAppender with no <target> writes to System.out, and that is what logback-stdout.xml in the demo does.

I expected the first application log line to break things. What happened is that the handshake failed before any application code ran. The SDK logs every initialize request at INFO, from McpAsyncServer, before it sends the response:

With INFO going to stdout, that line reaches the client ahead of the initialize result. Here is what the Java client's stdio transport does with a line it cannot parse (StdioClientTransport, v2.1.0):

It does not skip the line. It breaks out of the read loop, which completes the inbound stream, so the connection is dead for good. Each later request waits for the full request timeout, 20 seconds by default, and then fails. The transcript:

The second block is the dangerous one. Raising the root level to WARN hides the SDK's INFO line, so the handshake passes, tools/list passes, and a smoke test passes too. The session then dies on the first warning anyone logs, here a low-stock warning inside reserve_stock. Raising the level did not fix the bug. It only delayed the failure until the first call that logs something.

The fix has two layers. The first is the obvious one, the same appender pointed at standard error:

That only covers this one appender. A println left over from debugging, a library that prints a banner, or a dependency that brings its own logging configuration can each write to the same channel. The second layer does not depend on everyone behaving: take the real stdout for the transport before anything else runs, and point System.out at stderr for the rest of the process.

DemoServer calls it right after parsing its arguments, before a single tool or logger is created, because anything that runs earlier can still reach the real stdout. The fourth block of the transcript runs the broken logback-stdout.xml again with this guard enabled, and the session survives. Logback's console target writes through System.out each time it logs, so the redirect catches it as well. The 2026-07-28 revision deprecates the protocol's own Logging feature, and its suggested migration is "log to stderr (stdio) or use OpenTelemetry". Stderr is the right place for logs on stdio, not a workaround.

2. An exception where a result belongs

The tools chapter of the specification separates two kinds of failure. Protocol errors (unknown tool, malformed request, server errors) are returned as JSON-RPC errors. Tool execution errors (API failures, input validation, business logic) are returned inside the tool result, with isError: true. Then it says what each one is for: "Clients SHOULD provide tool execution errors to language models to enable self-correction", while for protocol errors clients only "MAY" do so, and "these are less likely to result in successful recovery."

Java makes the wrong choice the easy one. A handler that validates its preconditions the way Java code usually does looks like this:

The SDK turns any exception that is not an McpError into a protocol error. This is McpServerSession.toJsonRpcError:

So a cancellation refused by a business rule reaches the client with code -32603, which JSON-RPC defines as "Internal error": the code for a crashed server. In the Java client it shows up as a thrown McpError, not as a tool result. Whether the model ever sees it depends on the host. If it does, all it gets is the exception message:

The contrast is in the last call of each block, ORD-42. The SDK's own input validation, which checks the arguments against inputSchema before the handler runs, already uses the right channel and returns isError=true with the schema violation spelled out. Only the code we write ourselves takes the other path. The corrected handler returns the failure as data and writes the message for its actual reader, a model that has to decide what to do next:

Each message contains what happened (with the value), why, and what to do next. "Do not retry" matters as much as the reason. A model told only that something failed has nothing to stop it from trying again with slightly different arguments. Exceptions still have a place. A null pointer in your own code is a server error, and a protocol error is the honest way to report it. The rule is about failures you expected: if the handler code anticipates a case, its outcome is a result, not an exception. One side note. The SDK forwards getMessage() to the client unchanged, so an exception rethrown from a database driver can put SQL and hostnames in front of whoever is on the other end. That is a second reason to keep expected failures in your own words.

3. A catalog generated from the API

The response to tools/list is not documentation. Hosts put tool definitions in front of the model so it can choose among them, which makes the catalog part of the prompt, sent with every turn of the conversation. An API surface is built for a different reader. Mapping each REST endpoint to its own tool, which is what OpenAPI-to-MCP generators do by default, produces many narrow tools with schemas full of options (pagination, sparse fieldsets, includes, filters) that a model rarely needs and still has to read every time.

The demo builds both catalogs for the same order-management backend. EndpointCatalog does what a generator does: list, get, create, update and delete for each of the API's seven resources, whether the agent needs customers, products and warehouses or not. The task-shaped server has seven tools: six named after what this agent is for (search_orders, get_order, cancel_order, reserve_stock, start_export, export_status) and exports_written, a probe the demo uses to count side effects, left in so that the measured catalog is the one that actually ran. The comparison is therefore not like for like, and that is the point. A generator's catalog is sized by the API, while a designed one is sized by the job.

That is almost eight times the bytes (7.7), paid on every turn, before the model has done anything useful. The factor splits into scope and shape. Scope is five times as many tools. Shape is the rest: an endpoint tool averages 561 bytes against 363 for a task tool, 1.5 times as much, because every list endpoint carries the same seven generic parameters. I measured bytes, as the client re-serializes the result, not tokens, because the token count depends on the model's tokenizer and on how the host renders a definition. I also did not measure what 35 similar-looking tools do to the model's choice of tool. That needs a model and a sample size this demo does not have. So treat the following as an engineering rule, not a measured result: every tool in the catalog is a decision the model has to make on every turn. Fewer, task-shaped tools also shorten the work. "Cancel the oldest paid order" is one search_orders with status=paid and limit=1, then one cancel_order, which checks the status rule itself. Against the endpoint catalog, the model has to assemble the same thing from list_orders with a filter object, a sort expression and a page size, and then update_order with a body whose status values it has to guess.

The second half of this mistake is not about size. The 2026-07-28 revision adds a line to the tools chapter: servers "SHOULD return tools in a deterministic order", because that "improves LLM prompt cache hit rates when tools are included in model context." Prompt caches match an exact prefix, and the tool list sits near the start of it. In Java there is an easy way to break this without noticing: build the registry from Map.of.

The iteration order of the JDK's immutable Map.of and Set.of is randomized on purpose, so that nobody comes to depend on it. The JDK 27 source of ImmutableCollections is explicit: its salt "needs to vary sufficiently from one run to the next so that iteration order will vary between JVM runs", and a second flag reverses iteration "stochastically, decided at bootstrap time". That works against a server whose list order is meant to stay fixed. Five launches of the same server:

In the recorded run, five launches of the map version produced five different orders, and the list version produced the same order five times. The exact count changes from run to run, since varying it is the whole point of the salt. What the map never gives you is one fixed order. Unless the host sorts the tools itself, every restart of the server is therefore a likely cache miss for the prefix that follows them. Nothing errors and nothing logs, and the only symptom is a cache-hit rate that drifts down. The fix is a List in a fixed order, or, if the tools have to come from a map, sorting them by name before registering.

4. A result sized by the data

A tool whose output size depends on how much data happens to exist works fine in development and fails in production. The demo's list_orders is the honest version of that tool: it serializes the whole order book.

With 5,000 orders the call succeeds and returns 1.27 MB of text. Nothing fails, but the host now has to put about a megabyte of JSON into the context, cut it short, or drop it. None of those is a decision the server should be pushing onto the host. With 120,000 orders the result becomes a single line longer than the Java client will read. StdioClientTransport caps an inbound message at DEFAULT_INPUT_MAX_SIZE = 16 * 1024 * 1024 characters. Past that it logs the error, stops reading, and the connection ends exactly the way it did in mistake 1. The call times out after 20 seconds, and so does everything after it. One oversized result takes down every tool on that server.

The fix is to give the result a fixed upper bound and enforce it in the schema, so the bound holds no matter what the model asks for:

Several parts carry the weight here. "maximum": 50 in the input schema means the SDK rejects limit=500 before the handler runs; the transcript shows it coming back as a tool error with isError=true. Math.min enforces the same cap in code in case schema validation is ever turned off. The page holds summaries, not line items; anyone who needs the lines calls get_order, the tool the description points to. The result also declares an outputSchema and returns structuredContent, with the same JSON repeated as text because the specification asks for that "for backwards compatibility". That duplication is cheap only because the page is small. The Java client checks structuredContent against the tool's outputSchema, so the schema has to cover every page, including the last one: there next_cursor is null, which is why its type is ["string", "null"] rather than "string". The transcript's "last page" line is that case passing. With the type narrowed to "string" in a copy of the demo, the same call came back without its structured content. For data that really is bulk, such as a full export, the specification allows a resource_link content item instead of inline data. The demo does not use it, because a bounded page already covers what it needs.

There is one case where pagination is the wrong answer: when the caller needs an aggregate. A model asked for "revenue from shipped orders this quarter" should not page 5,000 summaries through its context to add them up. That question needs its own tool, which computes the sum on the server and returns a number.

5. A request that outlives the client

The specification expects both sides to give up on a slow request in a controlled way. Implementations "SHOULD establish timeouts for all sent requests". When one expires, the sender "SHOULD cancel the request", which on stdio means a notifications/cancelled message. SDKs "SHOULD allow these timeouts to be configured on a per-request basis", and a client "MAY" reset the timeout clock when progress arrives. Java SDK 2.1.0 implements less than that. Its timeout is one value per client, 20 seconds by default, applied to every request as a flat Reactor operator in McpClientSession.sendRequest:

Progress notifications do not extend it, and on expiry the client stops waiting without sending anything. The SDK has no cancellation support in either direction: issue #130, "Support cancellation", and PR #803 are both still open. So the server never learns that the client has given up, and keeps working:

The [bad] block is the failure in full. The client reports a timeout. The export finishes five seconds later anyway, so exports_written is 1. Then the second attempt, which is a reasonable thing for a host or a model to do after a "failure", writes a second export. The caller saw two failures, while the reporting bucket received two exports. A longer requestTimeout only moves the problem to the first export that runs longer than the new value. The specification also asks for an upper bound on timeouts, so a timeout has to exist somewhere.

The fix is to stop keeping the request open while the work runs. start_export returns a handle immediately, and the work runs off the request path. An idempotency key ties a retry to the export that already exists:

In the [good] block, both attempts get the same handle, the status moves from running to done, and exactly one export is written. The catch matters as much as the key. Without it, an export that throws never leaves "running", and the key that was meant to prevent a duplicate now prevents any retry at all, permanently. A handle needs a failure state, and a failure has to release the key. The [good, failing bucket] block forces that path: the first export fails, the same key starts a new one, and the count still ends at one. One limit of this approach needs saying plainly. An idempotency key protects retries that repeat the same arguments, which is what a host's automatic retry does. A model that decides to "try again" may invent a new key, and then the server sees two different requests. When duplicates are expensive, deduplicate on the business identity, meaning this export for this date and scope, and treat the key as an extra layer rather than the only one. The demo deduplicates on the key alone, so it covers the retry case and nothing more. The 2026-07-28 revision makes this pattern official as the io.modelcontextprotocol/tasks extension, with polling through tasks/get. Java SDK 2.1.0 does not implement it yet; issue #668 is open. Until it does, a handle tool and a status tool do the same job.

When this advice is wrong

Mistake 1 belongs to stdio. On Streamable HTTP the response travels on its own HTTP stream, and stdout is just a log. The same goes for the 16 Mi character limit, which belongs to the Java stdio client. Other clients and the HTTP transport have their own limits, which I did not measure. If you only ever run over HTTP, the first mistake does not apply to you. The fourth one still does, because the cost to the context window does not depend on the transport.

An endpoint-shaped catalog can be the right call. If the consumer is a developer tool driven by a person who wants the raw API, or the API is small enough that the endpoints already are the tasks, generating tools is cheap and honest. Hosts that load tool definitions on demand, rather than sending all of them every turn, weaken the size argument. They do not weaken the ordering argument.

A handle is state. Handles have to be stored, expired and authorized on every call. The specification's own note on stateful tools reminds you that a handle is "a name, not a capability". The demo keeps its handles in process memory and never expires them, which a real server cannot afford. For operations that reliably finish in well under a second, a plain call is simpler and better.

"Do not retry" is a request, not a rule. A model can ignore what a tool result tells it to do. The message improves the odds, while the server is what actually prevents the damage: a cancellation that refuses shipped orders, an export that deduplicates. The text of an error result is guidance for the model, not access control.

The demo is one SDK at one version. The break on an unreadable line, the missing cancellation and the flat timeout are behaviours of Java SDK 2.1.0, read from its source and observed in the run. The specification leaves a client free to skip a bad line, and other SDKs make other choices. What carries over to them is the question to ask your own client, not the exact answer this one gives.

A checklist for your own server

1. Nothing but protocol on stdout. Point every console appender at System.err, then reserve the real stdout for the transport and redirect System.out on startup, so that the next stray println cannot end the session.
2. Expected failures are results. Return isError: true with the value, the reason and the next step. Keep exceptions for bugs.
3. Design the catalog as a prompt. Name tools after tasks, not endpoints. Keep the order fixed by registering from a List, never from Map.of or Set.of.
4. Every result has an upper bound. Put a maximum in the schema, use a cursor, return summaries by default, and give aggregate questions their own tools.
5. Nothing slow holds a request open. Return a handle, give it a failure state that releases its key, deduplicate retries with an idempotency key and expensive work on its business identity, and assume the client gave up at the first timeout without telling you.

What the five have in common is that the protocol call succeeds, or fails somewhere other than where the mistake was made. The handshake log line is written by the server and kills the client's read loop. The exception is thrown in a handler and arrives as a crashed-server error. The catalog is generated once and costs something on every turn. The oversized result is valid JSON that the client refuses to read. The timed-out export completes and then gets written again. In each case the fix moves the decision back to the side that has the information: the server knows which lines are protocol, which failures it expected, how big its answers can get and how long its work takes. Making those limits explicit is the server's job, because the client and the model have no way to work them out.