MCP troubleshooting
My server broke after the spec update
Six causes, symptom by symptom, from a leftover handshake to retired error codes.
mcp-publisher authentication failed
DNS apex placement, stale keys, LibreSSL, org roles and PAT scopes.
MCP error: “Mcp-Session-Id header is required”
The server is running 2025-era session semantics against a client that speaks 2026-07-28. The header it is asking for no longer exists in the specification.
MCP OAuth: WWW-Authenticate has no scope parameter
The 401 is well-formed enough to start an OAuth flow, but it omits the one parameter that tells the client what to request. A client that guesses either over-asks — alarming the user — or under-asks and fails again after the round trip.
MCP error: Protected Resource Metadata missing or invalid
The 401 points a client at a metadata document, and the document is not there. The client has nowhere to go next: it cannot discover the authorization server, so it cannot get a token, so it cannot retry.
MCP error -32020: HeaderMismatch
A routing header and the request body are telling the server two different things. 2026-07-28 added this code precisely so the disagreement is reported as what it is, rather than as a generic parse or method error.
MCP error -32022: unsupported protocol version
The request is well-formed and its version is internally consistent — the server simply does not implement the revision being asked for. This is a negotiation outcome, not a malformed request.
MCP server and the Origin header: DNS rebinding, and the 403 you should be sending
This is the reverse of most entries here: the problem is not an error you received, it is an error your server failed to send. A request arrived from an origin it does not know, and it answered normally.
MCP OAuth: authorization server metadata not found
The chain gets one link further than a missing resource document and then stops. The client found your authorization server's identifier and went looking for its metadata; neither well-known path answered.