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.
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.