MCP OAuth debugging: find whose layer broke, from the outside
“Your MCP doesn't connect” is the commonest support ticket an MCP operator gets, and the failing layer is invisible from the server's own logs. mcpcomp doctor probes every layer reachable without credentials and classifies the failure.
mcpcomp doctor https://mcp.example.com/mcpFour layer verdicts and a classification, from the outside, in seconds.
Why MCP auth failures are hard to place
An MCP connection crosses four systems — the client, the MCP server, the authorization server, and the identity provider behind it. A failure in any of them presents identically to the user: the agent stops working. The server operator's dashboards are green because the requests that fail often never reach the server at all.
What doctor shows
Layer-by-layer verdicts
Discovery, authorization-server resolution, endpoint liveness, and protocol acceptance each get an explicit PASS, FAIL, or SKIPPED — the evidence trail for the classification, not just the conclusion.
A classification you can act on
Only requirement violations and operational outages decide the layer; advisories never do. A fully green server plus a failing client is itself the diagnosis — the commonest case, where the fix is reauthenticating the MCP connection in the failing client.
Runs inside the agent too
The scanner is itself an MCP server: mcpcomp serve exposes scan_auth and diagnose_auth_failure as read-only tools, so an agent whose MCP connection is failing can diagnose it without leaving the conversation.
Failures we have actually measured
These are not hypotheticals. Probing 27 production MCP deployments on 2026-08-20 found one that serves tools/list to any bearer string — the 401 it returns without a credential is a header-presence check, not a token check. Another drops its entire WWW-Authenticate header when the token is rejected rather than missing, so a client whose token just expired gets a bare 401 and no pointer back to discovery. Fourteen of fifteen never expose WWW-Authenticate to browsers, leaving browser-based clients able to see the 401 but not read it. Each of those looks identical from the operator's dashboard: green.
Why a debugger is not enough on its own
A debugger tells you what happened in the flow you just ran. It cannot tell you the reference client's own challenge parser silently ignores a DPoP challenge, a case-varied parameter name, or a multi-scheme header — all of which are conformant and all of which we found it dropping. Diagnosis has to account for what the client gets wrong as well as the server, which is why the layer classification is the output rather than a trace.
Frequently asked questions
Does doctor need access to my server or logs?
No. It works entirely from the outside using the same unauthenticated requests any client makes, which is exactly why it can see failures that never reach your logs.
What failure classes can it distinguish?
Network unreachability, server-side misconfiguration, authorization-server faults, and inferred client auth state — each named with the evidence that produced it.
Can an AI agent run the diagnosis itself?
Yes. Add mcpcomp serve as a stdio MCP server (or use the hosted endpoint at www.mcpcomp.dev/mcp) and the diagnosis tools become available in-conversation.
How is this different from an interactive OAuth debugger?
An interactive debugger walks you through a handshake you initiate, in a tool you have open, on a server you are already working on — it is a build-time instrument, and a good one. This runs credential-less against a server you may not control, classifies which of four layers the failure lives in, and can run on a schedule so the same check catches drift months later. The two answer different questions: what happened in this flow, versus which layer is broken right now.