Sign in to a remote MCP server in Claude Code: /mcp and claude mcp login

A developer has documented how to authenticate remote MCP servers in Claude Code, which requires a browser-based OAuth sign-in before hosted servers like Sentry, Linear and Notion become usable. Servers are added with `claude mcp add --transport http <name> <url>` and then authorized either through the `/mcp` panel or the shell command `claude mcp login <name>`, with tokens stored securely and refreshed automatically. The guide also covers `--callback-port` for fixed redirect URIs, passing a pre-registered client ID and secret, and headless sign-in over SSH using `--no-browser`.

Originally published at https://aicoding-guide.com https://aicoding-guide.com/en/posts/claude-code-mcp-http-oauth/ . Hosted MCP servers like Sentry, Linear and Notion are not usable the moment you register their URL. They need a browser sign-in first, and claude mcp list shows them as Needs authentication until you do it. In short: add the server with claude mcp add --transport http <name <url , then either run /mcp in a session and choose Authenticate on that server, or run claude mcp login <name from your shell. Tokens are stored securely and refreshed automatically. This article is part of a series. For every way to register a server, see Adding MCP servers to Claude Code https://aicoding-guide.com/en/posts/claude-code-mcp-servers-setup/ . Key point What you will learn - The two ways to sign in: /mcp and claude mcp login --callback-port for a fixed redirect URI, and how to pass a pre-registered client ID- What to do when a token expires or the browser never opens Register the server over the HTTP transport. The docs use Sentry as the example. claude mcp add --transport http sentry https://mcp.sentry.dev/mcp Right after adding, claude mcp list shows Needs authentication . That is expected; the sign-in clears it. Start a session, run /mcp , select the server from the list, press Enter and choose Authenticate . Your browser opens the service's sign-in page, where you approve the connection. Back in Claude Code the server's status changes to connected. Claude Code marks a remote server as needing authentication when it answers with 401 Unauthorized or 403 Forbidden . There is also a startup notice listing servers that need sign-in, so you do not have to open /mcp to find them v2.1.193 or later . Glossary Dynamic Client Registration : an OAuth mechanism where the client registers itself with the authorization server instead of you registering an app by hand. When a server supports it, passing the URL to claude mcp add is all the setup the sign-in needs. To sign in without opening a session, use claude mcp login . claude mcp login sentry To clear stored credentials later, run claude mcp logout <name . Over SSH, or on Linux without a display server, the command detects that no local browser is available and prints the authorization URL rather than trying to open one. Open that URL on your own machine, then paste the full redirect URL from the address bar back at the prompt. The paste step needs an interactive terminal, so connect with ssh -t . Pass --no-browser to force the URL prompt even when a browser is detected. claude mcp login sentry --no-browser Non-interactive runs claude -p , the Agent SDK have no /mcp panel, so Claude Code cannot run the OAuth flow there. As of v2.1.196, with tool search enabled, it tells Claude that the server's tools are unavailable until you authorize it, so Claude can name the server instead of acting as though it were not configured. Do the sign-in itself from an interactive session or with claude mcp login . If a server does not support Dynamic Client Registration, you get an error such as "Incompatible auth server: does not support dynamic client registration". Register an OAuth app through the service's developer portal and pass the credentials yourself. Servers that require a registered redirect URI expect the form http://localhost:PORT/callback . Pick a port, register it, and pass the same port to --callback-port : by default Claude Code picks a random free port, which will never match. | Flag / key | What it does | |---|---| | --callback-port <port | Fixes the callback port. Usable on its own | | --client-id <id | The client ID of your registered OAuth app | | --client-secret | Prompts for the secret with masked input | | MCP CLIENT SECRET | Supplies the secret through the environment, skipping the prompt | claude mcp add --transport http \ --client-id your-client-id --client-secret --callback-port 8080 \ my-server https://mcp.example.com/mcp In JSON, the same settings live in an oauth object. The secret stays out of the JSON and is passed with the separate --client-secret flag. claude mcp add-json my-server \ '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \ --client-secret oauth also takes scopes , which pins the scopes requested during authorization a single space-separated string, matching RFC 6749 , and authServerMetadataUrl , which overrides metadata discovery. { "mcpServers": { "slack": { "type": "http", "url": "https://mcp.slack.com/mcp", "oauth": { "scopes": "channels:read chat:write search:read" } } } } oauth.scopes takes precedence over authServerMetadataUrl and over whatever the server advertises at /.well-known . If the authorization server advertises offline access , Claude Code appends it so the token can be refreshed without another browser sign-in. The secret can only be set when you add the server The client secret is stored in your system keychain macOS or a credentials file, never in your config. You can set it only at add time: when you authenticate with claude mcp login or from /mcp , Claude Code uses the stored secret and neither prompts for one nor reads MCP CLIENT SECRET . To change it, run claude mcp remove <name and add the server again with --client-secret and the same --scope . Use claude mcp get <name to check whether credentials are configured. Which file each scope writes to is covered in claude mcp add scopes: local, project and user https://aicoding-guide.com/en/posts/claude-code-mcp-scope/ , and passing a static token through a header in Passing tokens from environment variables in .mcp.json https://aicoding-guide.com/en/posts/claude-code-mcp-json-env/ . When a request to a server you already signed in to returns 401 , Claude Code refreshes the stored token, reconnects and retries the request once. It flags the server in /mcp only if that retry also fails. When the server rejects the stored refresh token, a notice pointing at /mcp appears immediately. Open /mcp and choose Re-authenticate on that server. | Symptom | What to do | |---|---| | The browser does not open | Copy the URL shown in the terminal and open it manually | | The redirect fails with a connection error after you authenticate | Paste the full callback URL from the address bar into the URL prompt Claude Code shows | | A server with a configured Authorization header returns 401 or 403 | It will not fall back to OAuth; the connection is reported as failed. Check the token, or remove the header | | A tool call fails with 403 insufficient scope | Add the scope the server names to oauth.scopes , then authenticate again from /mcp | That last row catches people out: Claude Code requests the scopes you pinned, not the scope the server asked for, so signing in again without adding it gives you a token that still lacks it. One gap worth naming: the on-disk location of OAuth access and refresh tokens could not be confirmed in the official documentation . It says only that tokens are "stored securely and refreshed automatically", and names the keychain or a credentials file for the client secret alone. claude mcp add --transport http <name <url , then sign in from /mcp → Authenticate or with claude mcp login <name claude mcp logout <name or "Clear authentication" in the claude mcp login --no-browser prints the URL and takes the redirect URL back --client-id and --callback-port , plus --client-secret if the app has one oauth.scopes first