CLI flows

End-to-end flow walkthroughs

Start the server in one terminal:

uv sync --dev
uv run uvicorn mcp_auth_test_server.app:app --reload --port 8765

Run the following sequences from another terminal.

CIMD fixture clients

You can use the seeded dev-* clients instead of --register when you want predictable credentials: dev-public-client for the shared auth-code flow, dev-confidential-client for client credentials, and dev-admin-client for admin-scoped client credentials.

Add --verbose to discover, login, or call when you want protocol-level discovery and token exchange details.

Static bearer

uv run mcp-auth login 
  http://127.0.0.1:8765/mcp/bearer-token 
  --auth-mode bearer 
  --bearer-token test-bearer-token

uv run mcp-auth call http://127.0.0.1:8765/mcp/bearer-token initialize
uv run mcp-auth call http://127.0.0.1:8765/mcp/bearer-token tools/list
uv run mcp-auth call 
  http://127.0.0.1:8765/mcp/bearer-token 
  tools/call 
  --tool-name ping

Authorization code + PKCE

uv run mcp-auth discover http://127.0.0.1:8765/mcp/oauth

uv run mcp-auth login 
  http://127.0.0.1:8765/mcp/oauth 
  --auth-mode auth-code 
  --register

The CLI starts a localhost callback listener, prints the authorization URL, and waits for the browser redirect in the background. Open the URL and approve consent.

If you want to skip registration, use a seeded public client such as

--client-id dev-public-client instead of --register.

uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth initialize
uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth tools/list
uv run mcp-auth call 
  http://127.0.0.1:8765/mcp/oauth 
  tools/call 
  --tool-name echo 
  --tool-arguments '{"message":"hello","uppercase":true}'

Device flow

uv run mcp-auth login 
  http://127.0.0.1:8765/mcp/oauth 
  --auth-mode device 
  --register

The CLI prints verification_uri and user_code. Visit the URI, approve the code, then let the CLI finish polling.

uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth initialize
uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth tools/list
uv run mcp-auth call 
  http://127.0.0.1:8765/mcp/oauth 
  tools/call 
  --tool-name ping

Client credentials

uv run mcp-auth login 
  http://127.0.0.1:8765/mcp/oauth 
  --auth-mode client-creds 
  --register 
  --scope mcp:write

uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth initialize
uv run mcp-auth call http://127.0.0.1:8765/mcp/oauth tools/list
uv run mcp-auth call 
  http://127.0.0.1:8765/mcp/oauth 
  tools/call 
  --tool-name ping

Use --scope on client-credentials logins when you want to request a particular scope set, and use a seeded confidential client with

--client-id and --client-secret if you want to avoid dynamic registration.

Useful profile commands

uv run mcp-auth profile list
uv run mcp-auth profile show --resource-url http://127.0.0.1:8765/mcp/oauth
uv run mcp-auth logout http://127.0.0.1:8765/mcp/oauth