oauthdoctor

A read-only MCP OAuth discovery diagnostic. One inspect command tells you whether an MCP endpoint advertises its OAuth authorization metadata the way an agent expects to discover it. No login, no token exchange.

What it is

oauthdoctor is a command-line tool that walks the OAuth discovery flow an MCP client follows to find an endpoint's authorization server. It checks the 401 challenge, the WWW-Authenticate resource_metadata pointer, the Protected Resource Metadata document, the referenced authorization server metadata, and the PKCE S256 declaration. It is a discovery diagnostic, not a login tool and not a security certifier.

The problem it solves

A common failure: my MCP server returns 401 and the agent cannot find the authorization server metadata. The MCP Authorization spec expects the metadata to be discoverable through a specific chain of documents. oauthdoctor follows that chain read-only and reports where it breaks — so you can fix your server's discovery before an agent ever connects.

When to use it

• You run an MCP server and want to check whether its OAuth metadata is discoverable by an agent.
• You are debugging a 401 flow where the client cannot locate the authorization server.
• You want to confirm a Protected Resource Metadata document and PKCE S256 declaration are present and well-formed.

When NOT to use it

• You want to log in, exchange tokens, or run a PKCE roundtrip — oauthdoctor does none of those.
• You want a security certification of an OAuth implementation — a PASS only means the observed discovery documents passed the implemented checks.
• You want to scan for leaked tokens — this tool does not detect token leaks; it only inspects discovery metadata.

Installation

npm install -g oauthdoctor     # or run without installing:
npx oauthdoctor inspect <url> --json

Real command

npx oauthdoctor inspect https://mcp.example.com/mcp --json

What it checks

• HTTP 401 challenge on an unauthenticated request.
• WWW-Authenticate header carrying the resource_metadata parameter.
• Protected Resource Metadata document (RFC 9728) — fetched and validated.
• authorization_servers → Authorization Server Metadata: issuer, authorization endpoint, token endpoint presence and HTTPS.
• PKCE S256 code challenge method declaration.

HTTP targets are refused except 127.0.0.1 / localhost / ::1 (fixture mode) to keep the tool read-only against remote servers.

Example output

Representative structure of what oauthdoctor reports. A real public OAuth-protected MCP endpoint positive case has not yet been published by the project; the tool's local positive/negative fixture tests pass.

{
  "endpoint": "https://mcp.example.com/mcp",
  "status": "PASS",
  "checks": [
    { "name": "401_challenge", "status": "PASS" },
    { "name": "www_authenticate_resource_metadata", "status": "PASS" },
    { "name": "protected_resource_metadata", "status": "PASS" },
    { "name": "authorization_server_metadata", "status": "PASS" },
    { "name": "pkce_s256", "status": "PASS" }
  ]
}

Exit codes

Code	Meaning
0	PASS — all implemented discovery checks passed
1	FAIL — at least one implemented check failed (findings in JSON)
2	UNKNOWN — target could not be conclusively evaluated
3	usage error (bad arguments or non-HTTPS remote target)

What it does NOT check

• No login, no token exchange, no PKCE roundtrip, no refresh tokens.
• No audience enforcement testing.
• No credential storage or transmission.
• A PASS is not an OAuth security certification — only that the observed discovery documents passed the implemented checks.
• It does not detect token leaks; it inspects discovery metadata only.

Limitations

• Read-only against remote servers: only loopback HTTP targets are permitted (fixture mode).
• Covers the discovery chain (401 → resource_metadata → PRM → AS metadata → PKCE S256), not the full OAuth security posture.
• Experimental (0.1.0): local positive/negative fixture tests pass; a real public OAuth-protected MCP endpoint positive case has not yet been validated.

Status

Experimental (0.1.0). Local positive/negative fixture tests pass; a real public OAuth-protected MCP endpoint positive case has not yet been validated.

npm

Package: oauthdoctor — published by npm user eidonze, version 0.1.0, MIT.

GitHub

Source: xka0085-byte/oauthdoctor — issues and the full README live there.

Related tools

• mcpdoctor — the suite's broader MCP/x402 endpoint inspector; both are "is my MCP server ready?" diagnostics but focus on different layers (mcpdoctor = payment/discovery, oauthdoctor = OAuth metadata).
• ReceiptRail — a real MCP server; its authorization metadata could be the kind of endpoint oauthdoctor inspects.
• x402-reconcile — the suite's x402 402-challenge inspector.

Part of the Agent / Chain Evidence Tools suite · MIT · Node ≥ 18 · read-only, no keys, no payments