Authentication
Proxy uses OAuth 2.0 with PKCE and dynamic client registration per the MCP authorization spec. No API keys.
Overview
There are no API keys to create or paste. Proxy is an OAuth 2.0 protected resource, and MCP clients discover and complete the flow on their own.
| Step | What happens |
|---|---|
| 1 | Client sends a request to /mcp without a token and receives 401 |
| 2 | The WWW-Authenticate header names the protected resource metadata URL |
| 3 | Client reads the metadata, finds the authorization server, and registers itself (dynamic client registration) |
| 4 | Client opens the browser for sign-in with PKCE |
| 5 | Client retries with a bearer token; tools now work |
Discovery endpoints
| Document | URL |
|---|---|
| Protected resource metadata (RFC 9728) | https://mcp.useproxy.dev/.well-known/oauth-protected-resource/mcp |
| Authorization server metadata (RFC 8414) | https://mcp.useproxy.dev/.well-known/oauth-authorization-server |
| Resource identifier | https://mcp.useproxy.dev/mcp |
The 401 handshake
An unauthenticated initialize is expected to fail. This is the spec, not an outage:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
resource_metadata="https://mcp.useproxy.dev/.well-known/oauth-protected-resource/mcp"A compliant client follows resource_metadata and completes OAuth before retrying. Clients that never read that header cannot connect to any spec-compliant MCP server.
Redirect URIs
Dynamic client registration is open. A registration is accepted with any redirect URI, but authorize only completes for URIs that match an allowed pattern for known clients (Claude, ChatGPT, Cursor, Codex, Copilot, Zed, MCP Inspector, localhost). If your client is rejected at authorize time, contact [email protected] with the redirect URI.
Personal tokens
The CLI installer runs the browser flow once and issues a long-lived personal bearer token (prefix proxy_). Send it as Authorization: Bearer <token> on /mcp. Use it for clients that cannot open a browser or for scripted agents.
Reference
The agent-facing version of this page, in plain markdown, is at /auth.md.