Skip to main content

​
The doctor

From a credential-less probe, doctor classifies which layer a reported failure lives in: Only requirement violations and operational outages decide the layer; advisories never do. The verdict states only what the probe observed — a layer whose check was skipped is named as unobserved, never claimed as passing — and when high-severity advisories are present, the verdict flags them, because some are known to hard-block specific clients (a resource mismatch in the Protected Resource Metadata blocks Claude Code outright). A fully green server plus a failing client is itself the diagnosis — the commonest support case, where the server operator’s dashboards are green and the customer’s client is holding stale auth state.

​
Name the client, get the known bugs

With the failing client named (claude-code, codex, cursor or vscode), a CLIENT AUTH STATE verdict expands into that client’s documented failure patterns — condition, symptom, and the action that clears it:
Each pattern is distilled from reading the client’s source, changelog, or staff-confirmed reports — not speculation. The support flow this enables: tell the stuck customer to run one command, and the report that comes back answers whose layer it is and, when it is the client, which known bug.

​
End-to-end verification

verify makes a synthetic machine-to-machine connection through the MCP OAuth client-credentials extension: token issuance, then an authenticated tools/list. On failure it says which side of the token endpoint the fault is on — no token issued (credentials or authorization server) versus token issued but the call failed (the server’s own validation).
verify presents credentials, so it never runs without a client id and secret you provisioned — set MCPCOMP_CLIENT_ID and MCPCOMP_CLIENT_SECRET in the environment. There are deliberately no flags for them.

​
Use it from an agent

The scanner is an MCP server itself: serve (stdio) exposes scan_auth and diagnose_auth_failure as read-only tools. Add it to any MCP client and an agent whose MCP connection is failing can diagnose it without leaving the conversation — diagnose_auth_failure accepts the same optional client input as --client.