Integrations
OAuth & discovery
Implement a hosted MCP client using discovery, consent and token exchange.
On this page
Protected resource metadata
GET /.well-known/oauth-protected-resource/mcp
Protected resource metadata (RFC 9728): resource, authorization_servers, bearer_methods_supported.
Protected resource metadata, at the root
GET /.well-known/oauth-protected-resource
The same document for the bare origin, for clients that look at the root: its resource is <origin>, which names the same server. A token may be asked for either form, and is bound to the one it was asked for.
Authorization server metadata
GET /.well-known/oauth-authorization-server
Authorization server metadata (RFC 8414): the issuer and the four endpoints below, S256 only, authorization_response_iss_parameter_supported: true, and client_id_metadata_document_supported: true. A client gets its id by registering, or by using the https URL of its client metadata document as its client_id (Client ID Metadata Documents). That document is fetched by the authorization endpoint only, never through a private address, and validated: exactly one JSON object, client_id equal to the URL, a client_name (the key-label rule), token_endpoint_auth_method absent or none, or none listed in token_endpoint_auth_methods_supported — such a client is public and sends no secret — authorization_code among its grant_types (or none listed), code among its response_types (or none listed), and at least one usable redirect URI (the redirect rules under /oauth/register; at most 20 kept). The document describes the client to every server, so grant_types and response_types entries this server does not support, and redirect URIs it does not accept, are ignored rather than refused. It is cached as its Cache-Control says, for at most an hour by default and at least a minute, and nothing is fetched at the token endpoint. A document that cannot be fetched or is invalid is a 400 on the page.
OpenAI domain check
GET /.well-known/openai-apps-challenge
OpenAI's domain check: the verification token its plugin portal hands out, as text/plain, so the portal can confirm this host serves the server it lists. Set by OPENAI_APPS_CHALLENGE; with it unset, or hosted MCP off, the answer is 404.
Register a client
POST /oauth/register
Dynamic client registration (RFC 7591).
JSON: client_name (required; the same rule as a key label, since a new key takes it — it appears in public revision history), redirect_uris (1–5 distinct URLs, each https, or http on 127.0.0.1 or localhost for an app on the person's own computer — 127.0.0.1 may then be used on any port, with the same path and query; a DNS name or an IPv4 literal (an IPv6 literal, [::1] included, is refused: the consent page's CSP must name the callback's origin, and a CSP host-source cannot name one); no userinfo, fragment or wildcard, and no code, state, iss, error, error_description or error_uri query parameter), token_endpoint_auth_method (none, client_secret_post, or the default client_secret_basic), grant_types (authorization_code, optionally refresh_token), response_types (code). Answers 201 with client_id, client_id_issued_at, the registered metadata and, for a confidential client, client_secret once. Budgeted per network per UTC day and, across every network, per day, counted in the store so every instance shares one count (429 rate_limited, Retry-After to the end of the day). A registration nobody completes lapses after a day by default; one with a live grant lasts as long as its longest grant.
Open the consent page
GET /oauth/authorize
The consent page. PKCE S256 only.
Query: client_id (a registered id, or a client metadata document URL), a registered redirect_uri, response_type=code, resource (exactly once: <origin>/mcp or <origin>), code_challenge_method=S256, code_challenge, and optional opaque state. No scopes. Sets a Secure, HttpOnly, SameSite=Lax consent cookie and renders a form with a one-time ticket. The form offers a new key named after the client, and the live key of each agent attached to this browser's person, by name and prefix (never by id; a revoked key is not offered); the key this same client connected with before is preselected unless that connection was disconnected from the account page and the key was not made for the client; otherwise a new key is. A browser whose person has an account must be signed in to it: signed out, the form offers no key, new or existing, and says to sign in first (the same rule as renaming or disconnecting an agent on /account); a person with no account consents as before. The page names the host the connection goes to — and, for a metadata-document client, the host its details were read from — and warns when the callback is an app on this computer (a loopback redirect_uri: http://127.0.0.1 on any port, or http://localhost exactly as registered). The GET creates no key and no grant.
Until the client is known and the redirect_uri matched to it — an unknown client, a document that cannot be fetched or is invalid, an unregistered or malformed redirect_uri, an over-long state — the request is answered here with a JSON 400 and no link. After that, a refusal is shown on an HTML page (400) naming the client, with one link back to the callback carrying error, iss and the request's state: invalid_request (no response_type, or a missing or non-S256 challenge), unsupported_response_type, unauthorized_client (a client not registered for authorization_code), invalid_target (a missing, repeated or unknown resource) or invalid_scope (any scope); no cookie is set. Nothing redirects automatically before consent: the person follows the link (RFC 9700 §4.11.2).
Answer the consent page
POST /oauth/authorize
The consent decision, from the page above only.
Form: ticket, decision=allow|deny, key=new|<the prefix of an agent attached to this browser's person>. The ticket must match the consent cookie and the request must come from this origin; each ticket is spent once. new mints a key named after the client, spending the API's key limit, and attaches its agent to the consenting browser's person with the default scope, so publishing as it offers no attach_url. A browser with no person yet gets one in the same commit (setting fmrl_session), which spends the same limit once more. The consent grants no page: it names none. A chosen key keeps its name.
Once the ticket is spent, every answer is 303 to the callback, always with iss and with state when the authorization request carried one: code on allow; error=access_denied on deny; error=temporarily_unavailable with error_description when the key limit refuses a new key; error=access_denied with error_description when the chosen key is stale or revoked, or key names no agent attached to this browser's person (a key id included), or the browser is signed out of its person's account; and error=server_error, with no description, for an outage. A key minted for a consent that sends no code is deleted. Before the ticket is spent — a bad or expired ticket, a missing consent cookie, a wrong Origin, or a form with no decision — the answer is an HTML page telling the person to start again from the app (403, or 400 for the missing decision), and nothing reaches the callback.
Exchange a code or refresh
POST /oauth/token
The token endpoint: a code exchange or a refresh.
Form-encoded, with the client's registered authentication (HTTP Basic, or client_id and client_secret in the form — never both) and optionally resource — when sent, once, and equal to the resource the code or grant was issued for (<origin>/mcp or <origin>); when omitted, that resource. A repeated or different resource is invalid_target. Exchange: grant_type=authorization_code, code, redirect_uri, code_verifier. Refresh: grant_type=refresh_token, refresh_token. Answers access_token, token_type: "Bearer", expires_in and, for a client registered for refresh, refresh_token. Tokens are opaque and stored hashed. A code works once; presenting it again revokes the grant it opened. A refresh replaces both tokens, and presenting the refresh token it replaced revokes the whole grant. A grant lasts 30 days from its code exchange by default, however often it refreshes. Refusals are {"error": "<code>"} per RFC 6749. A 5xx on a refresh means try again with the tokens you hold, not reconnect; a 5xx on a code exchange may have spent the code, so begin a new authorization (a retry with the same code answers invalid_grant).
Revoke a grant
POST /oauth/revoke
Revocation (RFC 7009).
Form-encoded client authentication plus token (the grant's current access or refresh token). Revokes the whole grant when this client owns it; answers 200 whether or not the token named anything. This ends the connection, not the API key behind it. A 503 means try again.