Fix Claude Code MCP "needs authentication"

Quick answer

1. Start Claude Code and run /mcp.
2. Select the server that needs authentication and follow the steps in the browser window that opens to log in and approve access.
3. Run claude mcp list (or /mcp again) and check the server now shows ✔ Connected.

Prefer the terminal, or working over SSH? Run claude mcp login <name> instead (add --no-browser to get a URL you can open on another machine and paste the redirect URL back). To sign out later, run claude mcp logout <name>.

Why you see it

Claude Code marks a remote server as needing authentication when the server responds with 401 Unauthorized or 403 Forbidden, so you can complete the OAuth flow. OAuth in Claude Code applies to remote HTTP servers. A local stdio server does not use it; those take keys through environment variables (claude mcp add --env KEY=value ...), and a failing one is a different problem, covered in Fix MCP error -32000.

Claude Code stores the tokens it gets and refreshes them automatically. If a stored token is rejected, it refreshes and retries once before it flags the server again, so a flag that keeps returning usually means the refresh token was revoked or expired.

Add a server that needs sign-in, then authenticate

The example from the Claude Code docs adds Sentry's remote server. See also the Sentry MCP listing and the Notion and Linear servers, which use the same flow.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude
# then inside Claude Code:
/mcp

If you already added the server, running claude mcp add again with the same name at the same scope fails with a message that the server already exists. Skip straight to /mcp.

More on adding servers to Claude Code is in the best MCP servers for Claude Code.

If sign-in does not complete

The browser does not open, or the redirect fails

• If the browser does not open on its own, copy the URL Claude Code shows and open it manually.
• If the redirect shows a connection error after you approve access, copy the full callback URL from your browser's address bar and paste it into the URL prompt that Claude Code shows.
• Over SSH, or on Linux with no display, claude mcp login <name> detects there is no local browser and prints the URL instead. Open it on your own machine and paste the redirect URL back. It needs an interactive terminal for that paste step.

"MCP server needs you to sign in again"

The full message in the Claude Code docs is MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate). It means a sign-in expired or was revoked, or the token lacks a permission the tool needs. Run /mcp, select the server, and choose Re-authenticate. If the same error returns for one specific tool, the token may be missing a scope; Claude Code requests the scopes pinned in the server's config (oauth.scopes) when they are set, so add the missing scope there before signing in again.

You use claude -p or the Agent SDK

Headless runs have no /mcp panel, so Claude Code cannot run the OAuth flow there. Sign in once from an interactive session (/mcp, or claude mcp login <name> in your shell), then start the run again.

You set an Authorization header yourself

If the server entry has headers.Authorization (or a headersHelper) and the server rejects it, Claude Code reports the connection as failed rather than falling back to OAuth. Fix the token, or remove the header to use the OAuth flow. If the header comes from a ${VAR}, check that the variable is set; Claude Code warns about unset ones in claude mcp list and /mcp.

The server requires a pre-registered redirect URI or client

By default Claude Code uses a random free port for the OAuth callback. Servers that only accept a redirect URI of the form http://localhost:PORT/callback registered in advance need a fixed port, and some need a pre-registered client ID:

claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp

# with a pre-registered OAuth client (the secret is prompted for, masked)
claude mcp add --transport http --client-id your-client-id --client-secret --callback-port 8080 my-server https://mcp.example.com/mcp

The same server name is defined in two scopes

Claude Code stores OAuth sign-ins per endpoint. If one name points at different URLs in different scopes (for example a user-level and a project-level entry), signing in to one does not sign you in to the other, and claude mcp list warns about the conflict. Keep one definition and remove the rest with claude mcp remove.

Google, Microsoft 365 and other Anthropic-hosted connectors

Some Anthropic-hosted connectors, such as Gmail, Google Calendar and Microsoft 365, do not support local OAuth from Claude Code, because the identity provider only accepts the redirect URL registered by claude.ai. If Claude Code says so, connect the service at claude.ai under Customize, then Connectors, and remove your own entry with claude mcp remove <name>; the connector then appears in Claude Code on its own.

Start fresh

Choose Clear authentication from the server's menu in /mcp, or run claude mcp logout <name>, then authenticate again. If that still fails, claude mcp remove <name> and add the server again.

FAQ

Is "needs authentication" the same as "Failed to connect"?

No. Failed to connect means Claude Code could not reach or start the server, and claude mcp get <name> shows the HTTP status or error text. Needs authentication means it reached the server, and the server asked for credentials.

Does a local server (npx, uvx) use /mcp to sign in?

No. OAuth sign-in is for remote HTTP servers. For a local server, put the API key in its environment with --env or the env block of .mcp.json.

Can I do this for a team without everyone clicking through?

Each person signs in with their own account; tokens are stored per user. Teams can share the server definition through a project .mcp.json file, but not the credentials.