Home / MCP tooling

mcp-auth-doctor

Diagnose OAuth discovery problems on remote MCP servers.

Python · MIT · latest v0.1.0

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.

Install

pipx install git+https://github.com/basitalisandhu/mcp-auth-doctor                                 # isolated CLI install
uvx --from git+https://github.com/basitalisandhu/mcp-auth-doctor mcp-auth-doctor https://host/mcp  # run without installing
pip install git+https://github.com/basitalisandhu/mcp-auth-doctor                                  # into the current environment

From the README; see the full README for every option.

Releases

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