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

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.

Add the server and sign in from /mcp

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).

Sign in from the command line

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.

Use pre-registered OAuth credentials

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.

Which file each scope writes to is covered in claude mcp add scopes: local, project and user, and passing a static token through a header in Passing tokens from environment variables in .mcp.json.

When sign-in expires or fails

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.

Summary

• Add with claude mcp add --transport http <name> <url>, then sign in from /mcp → Authenticate or with claude mcp login <name>
• Revoke with claude mcp logout <name> or "Clear authentication" in the /mcp menu
• On a headless box, claude mcp login --no-browser prints the URL and takes the redirect URL back
• Without Dynamic Client Registration, use --client-id and --callback-port, plus --client-secret if the app has one
• A rejected refresh token means Re-authenticate in /mcp; a missing scope means editing oauth.scopes first