Based on each vendor’s official docs, checked October 28, 2026

MCP OAuth: connect a remote MCP server in Claude Code, Codex and Cursor

Remote MCP servers that hold your data usually ask you to sign in with OAuth instead of pasting an API key. The MCP specification makes authorization optional, but when an HTTP server uses it, the server acts as an OAuth 2.1 resource server and your coding agent acts as the OAuth client. This guide explains what happens during that sign-in, then shows the exact commands and config for Claude Code, Codex and Cursor, plus how to pin scopes and fix a redirect URI mismatch. Everything here comes from the MCP authorization specification and each vendor’s MCP docs, checked October 28, 2026.

1. 1. Claude Code: add the server, then sign in

   Add the remote server over HTTP, then run /mcp inside a session and finish the login in your browser. claude mcp login does the same from your shell, and --no-browser prints the URL for SSH sessions.

   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
   claude mcp login sentry

2. 2. Codex: add the server, then run codex mcp login

   Codex stores MCP servers in ~/.codex/config.toml (or a trusted project’s .codex/config.toml), shared by the CLI, IDE extension and ChatGPT desktop app. For an OAuth server, run codex mcp login with the server name.

   [mcp_servers.example]
   url = "https://mcp.example.com"
   
   # then, in your shell:
   # codex mcp login example

3. 3. Cursor: add the URL in mcp.json and authenticate

   Put the server URL in .cursor/mcp.json or ~/.cursor/mcp.json. Cursor signs in with the authorization code flow and PKCE, and registers itself as a public client when the server supports dynamic client registration.

   {
     "mcpServers": {
       "example": { "url": "https://mcp.example.com/mcp" }
     }
   }

4. 4. Check the connection

   In Claude Code, claude mcp list shows a status such as ✔ Connected or ! Needs authentication. In Codex, codex mcp list and /mcp in the TUI list your servers. In Cursor, check MCP Logs in the Output panel for authentication errors.

   claude mcp list
   codex mcp list

What happens when you sign in

The MCP authorization spec describes the flow. Your agent first calls the server without a token and gets HTTP 401 with a WWW-Authenticate header that points to the server’s Protected Resource Metadata (RFC 9728). That document names the authorization server, and the agent reads its metadata through OAuth 2.0 Authorization Server Metadata or OpenID Connect Discovery.

The agent then gets a client ID, opens your browser with a PKCE code challenge and a resource parameter naming the MCP server, and swaps the returned code for an access token. Every later MCP request carries Authorization: Bearer <token>; the spec forbids putting tokens in the URL query string.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

How your agent gets a client ID

The spec lists three ways: a Client ID Metadata Document (CIMD), a pre-registered client, or Dynamic Client Registration (DCR). Clients and authorization servers SHOULD support CIMD, while DCR is now described as deprecated and kept for backwards compatibility.

Codex’s docs say it supports both CIMD and DCR and picks CIMD automatically when the authorization server advertises it; you can force one with codex mcp login <server> --oauth-client-registration cimd or dcr. Claude Code’s docs say it discovers CIMD servers automatically. Cursor’s docs describe DCR plus static credentials.

When the server needs a pre-registered client

If Claude Code reports “Incompatible auth server: does not support dynamic client registration”, register an OAuth app in the provider’s developer portal and pass its client ID. Claude Code uses http://localhost:PORT/callback as the redirect URI, so fix the port with --callback-port.

Codex takes --oauth-client-id (and --oauth-client-secret for confidential clients) and prints the exact callback URL to register. Cursor takes an auth object with CLIENT_ID, optional CLIENT_SECRET and scopes, and uses fixed redirect URLs: http://localhost:8787/callback for the desktop app and https://www.cursor.com/agents/mcp/oauth/callback for web and Cursor Agents.

# Claude Code
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

# Codex
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Asking for fewer permissions

Per the spec, a server SHOULD list the scopes it needs in the WWW-Authenticate challenge, and clients SHOULD request only those. If a tool later needs more, the server answers 403 with error="insufficient_scope" and the client can step up to a wider token.

To pin scopes yourself: in Claude Code set oauth.scopes as one space-separated string in .mcp.json; in Codex set mcp_servers.<name>.scopes in config.toml or pass --scopes to codex mcp login; in Cursor set auth.scopes. If a refresh token needs offline_access, Cursor’s docs say to add it to auth.scopes.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": { "scopes": "channels:read chat:write search:read" }
    }
  }
}

Tokens, refresh and signing out

Claude Code stores tokens securely and refreshes them automatically; on a 401 with a stored token it refreshes, reconnects and retries once. Use Clear authentication in /mcp or claude mcp logout <name> to revoke, and claude mcp remove also deletes the stored tokens and client registration.

Cursor renews expired tokens with the server’s refresh token; if the server issues no refresh token you sign in again when the access token expires. Cursor’s cloud agents keep their own MCP sign-ins on Cursor’s servers, so signing out locally does not sign them out.

OAuth or a bearer token?

A static token is simpler for a server that only supports API keys: Claude Code takes --header "Authorization: Bearer ..." and Codex takes bearer_token_env_var. But if you set an Authorization header and the server rejects it, Claude Code reports a failed connection instead of falling back to OAuth, so remove the header to use OAuth. Local stdio servers do not use this flow at all: the spec says they should read credentials from the environment.

Tips

• Run claude mcp login with --no-browser over SSH and paste the redirect URL back at the prompt.
• If the browser redirect fails after you approve, paste the full callback URL from the address bar into Claude Code’s prompt.
• Register the exact callback Codex prints after codex mcp add; providers that exact-match redirect URIs reject anything else.
• Keep client secrets out of version control: Codex writes them to config.toml, and Cursor supports ${env:MCP_CLIENT_SECRET} in auth.
• Read the MCP security guide before connecting a server that can reach private data.

Next steps

Sources

• https://modelcontextprotocol.io/specification/latest/basic/authorization · checked 2026-10-28
• https://code.claude.com/docs/en/mcp · checked 2026-10-28
• https://developers.openai.com/codex/mcp · checked 2026-10-28
• https://cursor.com/docs/mcp · checked 2026-10-28