The step where your MCP server’s sign-in breaks

Give it the server’s URL. It walks the OAuth chain a client walks, from outside, with no credential and no client registration, and says which step breaks, whose it is — the server, its identity provider, or a known client bug, with the issue number — and the fix, citing the section of the spec that requires it.

Or from a terminal, or in CI:

npx --allow-git=root github:agentwares/mcp-oauth-doctor https://your-server.example/mcp
npx --allow-git=root github:agentwares/mcp-oauth-doctor https://your-server.example/mcp --client claude-ai --json

What it walks

1. One request with no token (server/discover at 2026-07-28, then initialize): it must answer 401 with a WWW-Authenticate challenge.
2. RFC 9728 protected-resource metadata: where the challenge points, then the well-known paths; its resource and authorization_servers.
3. RFC 8414 or OpenID Connect discovery, at the locations the 2026-07-28 spec lists in its order; the issuer must be identical (RFC 8414 §3.3); PKCE S256 must be advertised.
4. How a client gets a client ID: a client ID metadata document (preferred since 2026-07-28), dynamic registration (RFC 7591), or a pasted one.
5. The rules each client publishes — claude.ai, Claude Code, ChatGPT, VS Code, Cursor — and the bugs filed against them. Client verdicts are emulated from those sources; no client is run.

Error messages, explained

• “Authorization with the MCP server failed” — claude.ai and Claude Desktop (a named connector shows "Authorization with <Name> failed")
• “Couldn't reach the MCP server” — claude.ai and Claude Desktop
• “Failed to discover OAuth metadata” — the MCP Inspector, and Claude Code's debug log
• “Dynamic Client Registration not supported” — VS Code (a dialog), and the Codex CLI
• “Incompatible auth server: does not support dynamic client registration” — the MCP TypeScript SDK, so Claude Code, Cursor and other clients built on it
• “Issuer mismatch” — the MCP TypeScript SDK 2.x ("Issuer mismatch in authorization server metadata (RFC 8414 §3.3)"), Claude Code's 2026-07-28 runtime ("Issuer mismatch in authorization response (RFC 9207)") and Codex ("Authorization server issuer mismatch")
• “invalid_redirect_uri” — the authorization server, shown by Claude Code, Codex, Cursor and others after the consent redirect
• “Connection expired” — claude.ai web and Claude Desktop
• “token exchange failed” — what people search after ChatGPT's connector sign-in fails at the last step (we found no ChatGPT message with exactly these words)

Keep checking

Re-check it every hour and email me when a step breaks: agentcheck's free watch, no account — it follows the sign-in a new client follows, with these same rules.

Nightly, with history: mcpcheck Server Pro re-runs these sign-in checks against the server every night, with 90 days of history, and emails when one fails ($49 a server a month; the first run is free).

What it will not do

It never sends a credential, never registers a client and never retries. Every request has a ten-second timeout and identifies itself as agentwares-mcp-liveness/0.1 (+https://agentwares-agentcheck.vercel.app/bot). A URL must be public https: every address it resolves to, every metadata URL the server names and every redirect is checked first, and one caller gets 30 URL checks a minute per server instance. The same check is mcp_liveness_check_auth on this host’s MCP server, and npx --allow-git=root github:agentwares/mcp-oauth-doctor in a terminal or a GitHub Action.

Rules read on 8 October 2026. MCP Liveness · Terms · Privacy