Model Context Protocol breaking changes, updated weekly
Every verified Model Context Protocol trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all Model Context Protocol traps.
fg-0524· added 2026-10-15· last checked 2026-10-15
MCP server log messages stop reaching the client after moving to protocol 2026-07-28
Symptom
notifications/message from the server no longer appear in the client
Fix
Send io.modelcontextprotocol/logLevel in each request's _meta when you want logs, and keep stderr or your own log pipeline as the main record.
fg-0526· added 2026-10-15· last checked 2026-10-15
MCP server returns 400 or 404 on session id after initialize when it runs on several instances
Symptom
400 Bad Request on calls after a successful initialize
Fix
Run the server stateless (no session id generator), pin sessions to an instance, or keep session state in a shared store. The 2026-07-28 protocol removes sessions and the Mcp-Session-Id header entirely.
fg-0527· added 2026-10-15· last checked 2026-10-15
MCP tool names with dots are valid in MCP but rejected when forwarded to the Claude API
Symptom
400 invalid_request_error on a tools[].name when a custom client passes MCP tools straight to Claude
Fix
Name tools with letters, digits, underscores, and hyphens only, or map names in the client before sending them to the model and map them back on tool_use.
fg-0529· added 2026-10-15· last checked 2026-10-15
MCP TypeScript client gives 'MCP error -32001: Request timed out' after 60 seconds on a long tool
Symptom
McpError: MCP error -32001: Request timed out
Fix
Pass a larger timeout per call, set resetTimeoutOnProgress with an onprogress handler, and cap the total with maxTotalTimeout.
fg-0532· added 2026-10-15· last checked 2026-10-15
stdio MCP server fails with 'Unexpected token ... is not valid JSON' because something printed to stdout
Symptom
SyntaxError: Unexpected token ... is not valid JSON in the host's MCP log
Fix
Log only to stderr (console.error, the logging module), silence chatty dependencies, or upgrade dotenv to 18, which logs to stderr. The first character quoted in the error usually points at the stray line.
fg-0533· added 2026-10-15· last checked 2026-10-15
Streamable HTTP MCP server answers 406 Not Acceptable to a hand-written client
Symptom
Not Acceptable: Client must accept both application/json and text/event-stream
Fix
Send both media types in Accept on every POST and handle both a JSON body and an SSE stream in the response.
fg-0530· added 2026-10-15· last checked 2026-10-15
Python MCP server behind a proxy or custom domain rejects every request with 421 Invalid Host header
Symptom
421 Misdirected Request with body Invalid Host header in the server log
Fix
Pass transport_security with allowed_hosts and allowed_origins for the names you serve, listing both the bare host and host:* for ports, or turn the check off when a reverse proxy already controls Host.
fg-0521· added 2026-10-15· last checked 2026-10-15
400 HeaderMismatch from an MCP server on protocol 2026-07-28
Symptom
400 Bad Request with a HeaderMismatch JSON-RPC error, code -32020
Fix
Set the headers from the same values as the JSON body on every request, base64 encode a name that is not plain ASCII, and pick the version from the server's supported list.
fg-0522· added 2026-10-15· last checked 2026-10-15
mcp-publisher fails with 'NPM package is missing required mcpName field' although package.json has it
Symptom
NPM package '@scope/name' is missing required 'mcpName' field
Fix
Publish an npm version that contains mcpName, set packages[].version in server.json to that version, then publish to the registry.
fg-0523· added 2026-10-15· last checked 2026-10-15
MCP Registry cannot verify a Cargo crate that hides mcp-name in an HTML comment
Symptom
Publishing a crates.io server fails ownership verification
Fix
Put the mcp-name line in the README as visible text, for example a bullet in a links section.
fg-0525· added 2026-10-15· last checked 2026-10-15
MCP server on SDK v2 starts fine but tools/list fails because package.json still allows Zod 3
Symptom
client.listTools() returns an error pointing at fromJsonSchema() while the server keeps running
Fix
Declare zod ^4.2.0 in package.json, reinstall, and confirm a single copy with npm ls zod.
fg-0528· added 2026-10-15· last checked 2026-10-15
MCP TypeScript client fails with SdkError ERA_NEGOTIATION_FAILED against an older server
Symptom
ERA_NEGOTIATION_FAILED: Version negotiation failed: the server did not offer pinned protocol version 2026-07-28 via server/discover (no fallback in pin mode)
Fix
Use versionNegotiation mode auto and keep a 2025 revision in the supported list, so the probe falls back to initialize. Use mode legacy for servers that exit on any request before initialize.
fg-0531· added 2026-10-15· last checked 2026-10-15
server.tool is not a function, or SSEServerTransport is missing, after upgrading the MCP TypeScript SDK to v2
Symptom
TypeError: server.tool is not a function
Fix
Use registerTool, registerPrompt, and registerResource with a config object and a z.object schema. Serve Streamable HTTP; only a client limited to the old SSE transport still needs @modelcontextprotocol/server-legacy/sse.
fg-0534· added 2026-10-15· last checked 2026-10-15
TS2589 'Type instantiation is excessively deep and possibly infinite' when registering MCP tools
Symptom
TS2589: Type instantiation is excessively deep and possibly infinite
Fix
Align the project on one Zod 4 version and force it with an override when a transitive dependency pins another copy.
Have your agent check Model Context Protocol changes before it codes