MCP OAuth explained: how coding agents sign in to remote MCP servers

MCP OAuth is the authorization part of the Model Context Protocol specification. It applies to MCP servers reached over HTTP, such as https://mcp.linear.app/mcp. The MCP server acts as an OAuth 2.1 resource server, the agent acts as the OAuth client, and an authorization server signs the user in and issues tokens. Servers that run locally over stdio skip OAuth and read credentials from environment variables instead.

Authorization is optional in MCP. Many remote servers accept an API key in a header, and some accept both. Checked October 9, 2026 against the 2026-07-28 MCP specification, vendor documentation, and the live metadata of the servers named below. Replicas publishes this guide.

MCP server

Hosts the tools. It answers requests without a valid token with a 401 that points to its metadata.

MCP client

The agent or app calling the tools, such as Claude Code, Codex, or a cloud agent platform. It runs the sign-in and stores the tokens.

Authorization server

Signs the user in, asks for consent, and issues access and refresh tokens. It can be part of the MCP server or a separate identity provider.

A compliant client follows the same sequence the first time it connects. After that it reuses the stored tokens and only repeats the browser step when a refresh fails.

1. Get a 401 challenge

The client calls the server without a token. The server answers 401 with a WWW-Authenticate header whose resource_metadata parameter points to its protected resource metadata, often with a scope parameter.

2. Find the authorization server

The client reads /.well-known/oauth-protected-resource on the MCP server. Its authorization_servers field names the server that issues tokens.

3. Read the authorization server metadata

The client fetches /.well-known/oauth-authorization-server or /.well-known/openid-configuration from that issuer. It lists the authorize, token, and registration endpoints, and whether Client ID Metadata Documents are supported.

4. Get a client ID

The client uses a pre-registered client ID, a Client ID Metadata Document, or dynamic client registration. The next section covers all three.

5. Sign in through the browser

The client opens the authorize URL with a PKCE code challenge, a state value, and a resource parameter naming the MCP server. The user signs in and approves.

6. Receive the callback

The authorization server redirects the browser to the client's redirect URI with a one-time code. The client checks state and the iss parameter, then exchanges the code and PKCE verifier for tokens.

7. Call the server with a bearer token

Every MCP request carries Authorization: Bearer with the access token. When it expires, the client uses the refresh token instead of asking the user again.

An authorization server needs to know which app is asking before it shows a consent screen. Registering gives the client a client ID, a list of allowed redirect URIs, and sometimes a client secret. Traditional OAuth apps register by hand in a developer console. MCP clients connect to servers they have never seen, so the spec defines ways to do it without a person in the loop.

• Clients that support all three should try a pre-registered client first, then CIMD if the server advertises client_id_metadata_document_supported, then DCR if it publishes a registration_endpoint, and finally ask the user for client details.
• DCR creates a new client on each server for each installation. CIMD gives a client one identity it hosts itself, so servers can recognize it, show its name on the consent screen, and cache its metadata.
• Either way, the authorization server decides whom to admit. It can reject unknown client names, redirect URIs it does not accept, or any client it has not approved.

The redirect URI, or callback URL, is where the browser lands with the authorization code. Command-line agents start a short-lived HTTP listener on the loopback interface and register a localhost or 127.0.0.1 address, which works because the browser and the agent run on the same machine. Hosted apps register an HTTPS URL on their own domain.

• Servers that exact-match redirect URIs treat localhost and 127.0.0.1 as different. Claude Code 2.1.229 briefly sent 127.0.0.1 and failed against those servers until 2.1.231 restored localhost.
• A loopback callback proves nothing about which app is listening, since any local program can bind to localhost. That is one reason providers that want to control access check the client's identity rather than its callback URL.

When an agent runs in a cloud VM or container, the browser that finishes the sign-in is still on your laptop. The provider redirects that browser to localhost, which now means your laptop, where nothing is listening. The code never reaches the agent, and the sign-in hangs or shows a connection error.

Disposable environments make it worse. A fresh VM for each task has no saved tokens, so an agent that signs in inside the sandbox has to do it again for every task, with someone at a browser to finish it.

Paste the redirect URL back

Claude Code prints the authorization URL when it has no browser. Open it locally, then copy the failed localhost URL from the address bar back into the prompt. It works once per machine, by hand.

Forward the callback port

Fix the port with --callback-port or mcp_oauth_callback_port and forward it over SSH, so localhost on your laptop reaches the VM. It needs an interactive session.

Use a callback the VM can receive

Codex's mcp_oauth_callback_url can point at an ingress URL that reaches the VM. The provider must accept that redirect URI.

Copy tokens from a local sign-in

Fragile. Access tokens expire, and copying credentials into every sandbox spreads long-lived secrets.

Figma's remote server at https://mcp.figma.com/mcp follows the discovery steps above and publishes a registration endpoint, but it does not accept every client. Figma's developer docs say only clients listed in the Figma MCP Catalog can connect, and a Figma staff reply on its forum says the server allowlists client_name during dynamic client registration while the feature is in beta. A client that is not on the list gets 403 Forbidden from the registration endpoint before any sign-in page appears.

Changing the callback URL does not help, because the check is on the client's identity. The catalog includes clients such as Claude Code, Cursor, VS Code, and Codex, and other developers can join Figma's waitlist for client support.

• Use a client listed in the Figma MCP Catalog.
• Use Figma's desktop MCP server, which runs locally through the Figma desktop app. A cloud VM cannot reach it.
• Use the Figma REST API with a personal access token to read files. It does not offer the MCP server's tools.
• Do not send an approved client's name to get past the allowlist. It impersonates another app and can stop working whenever Figma tightens the check.

Most connection failures happen at registration or at the callback, before the agent calls a single tool.

Incompatible auth server: does not support dynamic client registration

Claude Code shows this when the authorization server has no registration endpoint. Supply a pre-registered client with --client-id, or use an API key header if the server accepts one.

403 Forbidden during registration

The server only admits approved clients, as Figma does. Use an approved client or another way to reach the service.

invalid_redirect_uri or redirect URI mismatch

The server only accepts registered callbacks, or matches them exactly. Check localhost versus 127.0.0.1, the port, and the path.

The browser sign-in never returns

The callback points at localhost on a different machine than the agent, which is common over SSH and in containers and cloud VMs.

invalid_grant when refreshing

The refresh token expired or was revoked, or the user removed the app. Sign in again.

401 after a successful sign-in

The token was issued for a different resource. Check that the MCP URL, including its path, matches the resource the server advertises.

In Replicas, MCP servers belong to an environment. Add an HTTP or SSE server, choose OAuth, and click Connect. Replicas discovers the authorization server, registers itself with dynamic client registration, and runs the PKCE sign-in through its hosted callback. The registration and tokens are stored encrypted and refreshed by Replicas, and a local proxy in each workspace adds a current token to every request, so tokens never appear in the sandbox's MCP config.

Every workspace in that environment then starts with the MCP connected, whether it runs Claude Code, Codex, or OpenCode. Add the MCP to a personal environment to keep the account private. Replicas does not yet support CIMD or pre-registered client IDs, so servers without a registration endpoint, or with a client allowlist like Figma's, only work if they also accept an API key header. Replicas includes a 14-day free trial with no credit card required.

• MCPs in Replicas environments

  Add stdio, HTTP, and SSE MCP servers, including OAuth sign-in.

• Background coding agents

  How background agents take delegated work and report back.

• Cloud development environments for coding agents

  Nine platforms for running agents in isolated cloud environments.

• MCP authorization specification

  The normative flow, discovery, and token rules.

• MCP client registration

  Pre-registration, CIMD, and dynamic client registration, in priority order.

• Claude Code MCP documentation

  OAuth sign-in, callback ports, and pre-configured client credentials.

• Codex MCP documentation

  codex mcp login, callback settings, and header authentication.

• Figma MCP server guide

  Figma's remote and desktop servers and its client catalog.