MCP OAuth

Client registration

OAuth for a remote MCP server requires a configured public web URL for the instance.

Some servers support client metadata documents and have no registration endpoint. For those, the plugin publishes a public HTTPS client document at /hooks/mcp/oauth/client-metadata.

The document's URL is the client ID, and it declares the instance's /p/mcp/oauth/callback as the redirect. It contains no credentials, account data or server configuration.

Keep the public HTTPS origin and the document address stable for as long as the connection is used, including later token refreshes. Changing the public origin and restarting changes the client ID and the callback, so every authorization has to be repeated.

Disabling the MCP plugin removes the public document, and the authorization server can then no longer identify this client.

A server with a registration endpoint uses dynamic client registration, even when it also advertises client documents.

Callback state

The pure apiContract.mjs callback descriptor uses the original arbitrary-JSON wire schema, parsed lazily by the route. State shape, consumption, actor, expiry and server revision remain in the OAuth owner. In particular code/error/issuer validation must not move ahead of claiming a known state: failed callbacks consume that state too. Malformed JSON still returns 400 invalid_state; known state expiry is 410, actor mismatch 403 and stale state/revision 409. Credentials remain in the vault; descriptors contain no tokens or native client handles.

The callback page reads its state; an address without one is an invalid request and sends nothing. The request is claimed once, before account, expiry and revision checks, so two concurrent callbacks cannot exchange the same authorization code twice.

The page shows a loading state while it confirms the sign-in, then a short confirmation, and returns to /p/mcp so that Back cannot submit the callback again.

Expired, unrecognized, denied and failed requests show their own message; a network failure or an unexpected answer shows a general failure without server details. Failures are not replayed — a new sign-in has to be started from MCP.

Failed setup and diagnostics

An HTTP server that requires OAuth stays stored when authorization is needed, and also when OAuth discovery or client registration fails. A failed setup shows Sign-in error with a diagnostic that names the failed phase or the HTTP status, and both the error and its sign-in action survive an Elowen restart.

Provider response bodies are never displayed. Other verification failures are reported without keeping the change.

Credential identity

Credentials are keyed by owner, server name and address, so a new address needs its own sign-in even when it reaches the same server. Tokens stay in the host's encrypted secret namespace; see MCP persistence for storage and locking.

Switching from a stdio OAuth proxy to a direct HTTP connection therefore means adding the HTTP server and signing in to it, then verifying the connection and its tools before the proxy is retired.

Legacy SSE servers

Stored SSE servers are unsupported and never connect, and their address is not migrated automatically. Open the server, select Streamable HTTP, enter the streamable HTTP address and save; until a supported transport is selected, saving stays disabled. The web page, the CLI and Reconnect all skip such servers instead of retrying them.