Claude Code 中远程 MCP 服务器登录指南：/mcp 与 claude mcp login

Originally published at https://aicoding-guide.com. 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 , then either run /mcp in a session and choose Authenticate on that server, or run claude mcp login 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. 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 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 Enter fullscreen mode Exit fullscreen mode 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. Sign in from the command line To sign in without opening a session, use claude mcp login. claude mcp login sentry Enter fullscreen mode Exit fullscreen mode To clear stored credentials later, run claude mcp logout . 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 Enter fullscreen mode Exit fullscreen mode 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 Fixes the callback port. Usable on its own --client-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 Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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" } } } } Enter fullscreen mode Exit fullscreen mode 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 and add the server again with --client-secret and the same --scope. Use claude mcp get to check whether credentials are configured. 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 , then sign in from /mcp → Authenticate or with claude mcp login Revoke with claude mcp logout 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