OAuth Login & Debugging

Authenticate with MCP servers and debug OAuth flows

The oauth command group handles authentication against MCP servers that require OAuth. Use oauth login to obtain tokens interactively, and the proxy/metadata commands to debug discovery and endpoint behavior.

Quick start

# Interactive login — opens a browser for consent
mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 \
  --registration dcr

On success, the command prints credentials such as an access token, refresh token, client ID, and sometimes client secret. You can pass access tokens to other commands via --oauth-access-token or --access-token.

Commands

oauth login

Runs a full OAuth flow: discovery, registration, authorization, token exchange. Supports all three registration strategies and auth modes.

# DCR + interactive (most common for local dev)
mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 \
  --registration dcr

# CIMD + interactive (2025-11-25 only)
mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 \
  --registration cimd

# Preregistered + client_credentials (M2M, no browser)
mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 \
  --registration preregistered \
  --auth-mode client_credentials \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET"

Prefer environment variables for --client-secret. Passing it inline leaks to shell history and process listings.

The --credentials-out <path> flag saves OAuth credentials to a file with 0600 permissions. Depending on the flow, the file may include an access token, refresh token, client ID, and client secret. Secret fields are redacted from stdout output. Use the saved file with --credentials-file on other commands.

mcpjam oauth login --url https://your-server.com/mcp \
  --credentials-out creds.json

# Then reuse across commands
mcpjam tools list --url https://your-server.com/mcp --credentials-file creds.json
mcpjam server doctor --url https://your-server.com/mcp --credentials-file creds.json

The --debug-out <path> flag captures a structured debug artifact with full HTTP traces — useful for filing bug reports or handing off to another engineer.

mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 \
  --registration dcr \
  --debug-out oauth-debug.json

oauth metadata

Fetch and display OAuth metadata from a URL. Useful for verifying your server’s discovery endpoints are correct.

mcpjam oauth metadata --url https://your-server.com/.well-known/oauth-protected-resource
mcpjam oauth metadata --url https://auth.example.com/.well-known/oauth-authorization-server

oauth proxy

Send an arbitrary HTTP request through the OAuth proxy with hosted-mode safety checks. Useful for testing individual OAuth endpoints (registration, token, etc.) without building raw HTTP requests.

# Test a DCR registration
mcpjam oauth proxy \
  --url https://auth.example.com/register \
  --method POST \
  --header "Content-Type: application/json" \
  --body '{"redirect_uris":["http://localhost:8080/callback"],"client_name":"test"}'

# Fetch an endpoint
mcpjam oauth proxy --url https://auth.example.com/v1/oauth2/token --method GET

oauth debug-proxy

Same as oauth proxy but routes through the debug proxy path. Use when testing endpoints that behave differently for debug vs. production requests.

Login flags

Flag	Required	Default	Description
--url <url>	Yes		MCP server URL
--protocol-version <v>	Yes		2025-03-26, 2025-06-18, or 2025-11-25
--registration <s>	Yes		cimd, dcr, or preregistered
--auth-mode <m>	No	interactive	headless, interactive, or client_credentials
--client-id <id>	No		OAuth client ID (required for preregistered)
--client-secret <s>	No		OAuth client secret
--client-metadata-url <url>	No		CIMD metadata document URL
--redirect-url <url>	No	Auto-generated	OAuth redirect URL
--scopes <scopes>	No		Space-separated scope string
--header <header>	No		HTTP header Key: Value (repeatable)
--step-timeout <ms>	No	30000	Per-step timeout
--verify-tools	No		After login, connect and list tools
--verify-call-tool <name>	No		After listing, also call a named tool
--credentials-out <path>	No		Write OAuth credentials to file (mode 0600); stdout output has secret fields redacted
--debug-out <path>	No		Write debug artifact to file

For interactive login, a custom --redirect-url must still be an http://localhost or http://127.0.0.1 loopback URL. Custom callback paths are supported.

Using tokens from login

Credentials file (interactive & agent workflows)

For interactive or agent workflows where you login once and run multiple commands, save credentials to a file:

# Login and save credentials
mcpjam oauth login --url https://your-server.com/mcp --credentials-out creds.json

# Reuse across commands
mcpjam tools list --url https://your-server.com/mcp --credentials-file creds.json
mcpjam server doctor --url https://your-server.com/mcp --credentials-file creds.json
mcpjam protocol conformance --url https://your-server.com/mcp --credentials-file creds.json

The credentials file includes the server URL and any reusable OAuth credentials returned by the login flow. The CLI validates that the file’s server URL matches the target and checks token expiry before use.

Connected commands such as tools list, resources list, prompts list, and server doctor can use refresh-token credentials from the file when the saved access token is expired. protocol conformance and server probe only read a non-expired access token from the file; if the access token is expired, run oauth login --credentials-out again or pass a fresh token directly.

--credentials-file cannot be combined with --access-token, --oauth-access-token, --refresh-token, --client-id, or --client-secret. The CLI rejects conflicting auth sources upfront.

Direct token passing (CI/CD & M2M)

When you already have a token from an environment variable, a secret store, or a client_credentials flow, pass it directly:

# From an environment variable or secret store
mcpjam tools list --url https://your-server.com/mcp --access-token "$TOKEN"
mcpjam server doctor --url https://your-server.com/mcp --oauth-access-token "$TOKEN"

# M2M: preregistered client_credentials — token comes back on stdout
TOKEN=$(mcpjam oauth login --url https://your-server.com/mcp \
  --protocol-version 2025-11-25 --registration preregistered \
  --auth-mode client_credentials \
  --client-id "$CLIENT_ID" --client-secret "$CLIENT_SECRET" \
  --format json | jq -r '.credentials.accessToken')

mcpjam tools list --url https://your-server.com/mcp --access-token "$TOKEN"

You can also use --refresh-token with --client-id (and optionally --client-secret) for commands that support automatic token refresh.