mcp-auth-doctor
Diagnose OAuth discovery problems on remote MCP servers.
What it is
One read-only command that explains why a remote MCP server's OAuth login fails. It does what a conforming MCP client does when it meets a server, step by step, and reports each step as pass, fail, warn or skip with a one-line reason and the evidence: the unauthenticated 401, the WWW-Authenticate challenge, Protected Resource Metadata (RFC 9728), authorization server metadata (RFC 8414 or OpenID Connect Discovery), PKCE S256, client registration options, the RFC 9207 iss parameter and the token endpoint's error format. Optionally it runs the whole PKCE login and calls tools/list with the token.
Checked against the MCP authorization specification, both the 2026-07-28 release and 2025-11-25. Python 3.11+, one dependency (httpx), runs with pipx or uvx.
It is for people who run or build a remote MCP server, and for anyone whose MCP client says "OAuth failed" and wants to know which step broke.
Install
pipx install git+https://github.com/basitalisandhu/mcp-auth-doctor
mcp-auth-doctor https://your-server.example.com/mcp # read-only; add -v for evidence
mcp-auth-doctor https://your-server.example.com/mcp --json > report.json
From the README; see the full README for every option.
Links
Releases
More in MCP tooling
- dev-mcp-servers: Ten small MCP servers for everyday development and security checks.
- mcp-server-template: Secure MCP server template in TypeScript and Python, safe by default.
- mcp-tools-lint: Lint MCP tool schemas and annotations before clients reject them.
- mcp-egress: Record every host an MCP server contacts, per tool, and fail CI on new ones.
- claude-mcp-allow: Least-privilege Claude Code permission rules for MCP tools, generated from their annotations.
- agentdojo-mcp: Run the AgentDojo benchmark's user and injection tasks against a real MCP server's tools.
- garak-mcp-probes: Run garak against your own MCP servers, with detectors for denied tool calls, leaked canaries and runaway step counts.
- mcp-rc-check: MCP specification migration checker for the 2026-07-28 revision: flags removed, changed and deprecated constructs and writes a patch for mechanical fixes.
Topics: authorization, claude-code, cli, developer-tools, diagnostics, hacktoberfest, mcp, mcp-server, model-context-protocol, oauth, oauth2, openid-connect, pkce, python, rfc8414, rfc8707, rfc9728, security-tools