OAuth with RouterMCP

OAuth appears in two separate places in RouterMCP:

These flows have separate issuers, client registrations, and tokens. Authorizing a client for a project does not authorize RouterMCP to access an upstream provider, and connecting an upstream account does not grant a client access to the project.

Let clients connect to a project with OAuth

1. Open the project’s Access page and set Access mode to OAuth 2.1.
2. Open the project’s Connect page and copy the Project MCP endpoint shown there. Use that endpoint as displayed. OAuth project endpoints do not use the /request suffix.
3. Add the endpoint to an OAuth-capable MCP client and complete the sign-in and consent flow when the client prompts you.

The project endpoint is the resource protected by OAuth. Clients discover the protected-resource and authorization-server metadata at these project-scoped paths, where <project-endpoint> is the endpoint copied from Connect:

<project-endpoint>/.well-known/oauth-protected-resource
<project-endpoint>/.well-known/oauth-authorization-server

The authorization-server metadata advertises support for Client ID Metadata Documents (CIMD), provides the Dynamic Client Registration (DCR) endpoint at <project-endpoint>/api/auth/register, and supports PKCE with S256 only. A client that uses CIMD identifies itself with the HTTPS URL of its metadata document as its client_id. The metadata document must be publicly fetchable by the authorization server.

Connect a project to an OAuth upstream server

From the project’s Servers page, choose Add Server, enter the remote MCP endpoint, and select OAuth as its authorization method. Then use Connect on the new server and authorize the account that should own that connection.

For a fresh upstream connection, RouterMCP selects a client registration in this order:

1. It uses a client ID and optional secret you explicitly configured, or reuses a stored registration when it belongs to the same issuer.
2. If the upstream authorization server advertises client_id_metadata_document_supported: true and RouterMCP can use its stable public HTTPS metadata document, RouterMCP uses that document URL as the client_id. This CIMD flow uses the public-client authentication method none; it does not require entering a secret in RouterMCP.
3. If automatic CIMD selection is unavailable and the upstream metadata provides a registration_endpoint, RouterMCP tries DCR. The automatic DCR request also uses the public-client method none.
4. If neither automatic option is available, configure a pre-registered client in OAuth Client Advanced Settings. Enter the client ID and, when the upstream provider requires one, the provider-issued client secret. Register the callback URL shown in those settings with the provider. These are credentials for that upstream provider, not a RouterMCP API key.

If the upstream issuer changes, connect again for the new issuer. A stored CIMD or DCR client ID from the previous issuer is not reused; replace a static client configuration that was issued for the previous issuer.

If RouterMCP has selected CIMD and the upstream rejects the client metadata or client ID, do not assume RouterMCP will retry with DCR. Resolve the CIMD validation problem or use a pre-registered client if the provider supports one.

RouterMCP client metadata URLs

RouterMCP publishes public metadata documents for its own OAuth clients at the canonical RouterMCP origin:

Both documents declare token_endpoint_auth_method: none. The documents are public and do not require a RouterMCP API key or client secret. The native CLI redirect is a literal loopback URI. The CLI may choose an available numeric port at runtime; the scheme, literal host 127.0.0.1, path, and query must still match the registered URI. Use a CLI release that supports this redirect; the existence of the hosted metadata document does not establish which npm package release contains that support.

CIMD is described in an Internet-Draft and is not a finalized RFC. When checking a flow, inspect the decoded client_id parameter in the authorization request. Exact equality with the client’s metadata-document URL identifies CIMD for that request. An opaque client ID alone does not prove DCR: static registrations can also use opaque IDs.

A shared CIMD client identity does not share authorization grants between RouterMCP projects. Each project authorizes the client independently, and each project’s granted access remains scoped to that project.

Verify both OAuth directions

Use two RouterMCP test projects, Target and Caller, to exercise the two OAuth roles together. This is a test procedure, not evidence that the flow has already been verified in production.

1. Target project: Set Access mode to OAuth 2.1. Add a harmless read-only upstream tool and enable it, then copy the Target Project MCP endpoint from its Connect page.
2. Caller project: Add a fresh remote server using the copied Target endpoint and select OAuth. Leave OAuth Client Advanced Settings empty, then start Connect. On Target’s consent screen, confirm the application is RouterMCP and the client metadata host is www.routermcp.com. Inspect the authorization request’s decoded client_id and confirm it is exactly https://www.routermcp.com/oauth/client-metadata.json. Approve consent and confirm the server is connected in Caller. In Caller, refresh the tool list and use Tools → Run tool on the enabled read-only tool.

This fresh Caller server exercises CIMD. An existing server at the same issuer may reuse a stored client ID, so a successful connection by itself does not show that CIMD ran. Check the decoded client_id. To test DCR separately, use a fresh external test server whose authorization metadata does not advertise CIMD and includes a registration_endpoint; confirm registration, complete Connect, and run an enabled test tool. A 200 from a public metadata URL confirms that the document is reachable; it does not prove that a client accepted it, authorization completed, tokens were issued, or a tool call works.

After connection, a Connected status alone does not prove upstream tools can run. Refresh the tool list and use Tools → Run tool with an enabled tool. If the test provider returned a refresh token and the connected server’s UI offers Refresh Token, exercise that action in the test project. Do not remove real credentials to force a refresh test.

Troubleshooting

• CIMD is not selected: Confirm the upstream metadata advertises client_id_metadata_document_supported: true and RouterMCP can use its stable public HTTPS metadata document. If automatic CIMD selection is unavailable, RouterMCP tries DCR when a registration_endpoint is present. If an upstream rejects an already selected CIMD client ID, a DCR retry is not guaranteed.
• Registration is rejected: Check that the upstream endpoint is the authorization server’s registration_endpoint. If it does not support DCR, use a pre-registered client in OAuth Client Advanced Settings.
• OAuth fails after an issuer change: Reconnect to the new issuer. Replace any static client ID or secret that belongs to the old issuer.
• A CLI session stops working after its issuer changes: Reauthenticate the CLI session so it is bound to the new issuer. Older cached sessions may need this reauthentication.
• The metadata URL returns 200, but the connection fails: Check the authorization request’s decoded client_id, registered redirect URI, PKCE S256, provider response, and token exchange. A metadata response alone verifies document availability only.