Claude Code: MCP OAuth loops or never finishes

The symptom

You ran claude mcp add for a remote server. A browser tab opened, asked you to authorize, and then either looped back to the auth screen or returned to a blank page. Back in the CLI, claude mcp list shows the server but its tools are unavailable.

Fix 1: use the http transport explicitly

Remote MCP servers need --transport http. Without it, Claude Code may treat the entry as a stdio server. The OAuth handshake never starts. You are left waiting on a browser tab that never settles.

claude mcp add --transport http hjarni https://hjarni.com/mcp

Add --scope user to make the server available across every Claude Code project, or omit it to scope to the current project.

Fix 2: free the callback port (only if you pinned one)

Claude Code picks a random free port for the OAuth callback by default. This step only applies if you set --callback-port explicitly (or pinned one through a corporate proxy rule). In that case, another process bound to the same port leaves the browser redirect with nowhere to land and the loop never closes.

Quit anything else bound to that port, or drop the explicit flag and let Claude Code pick its own.

Fix 3: remove and re-add

A half-completed OAuth handshake leaves a stale token behind. Subsequent attempts try to refresh it, fail silently, and bounce you back to authorize.

claude mcp remove hjarni
claude mcp add --transport http hjarni https://hjarni.com/mcp

Fix 4: check the scope you registered at

You can register an MCP server at user scope or project scope. A duplicate at the wrong scope can intercept the request. List both and clean up:

claude mcp list             # current scope
claude mcp list --scope user # user-scoped servers

If the same server is registered twice with different URLs (for example one pointing at a staging host), remove the one you do not want.

If the server is yours: check the redirect URI allow-list

If you are running the MCP server, make sure the OAuth client allows the redirect URI Claude Code uses. The exact URI is printed in the browser tab; copy it from the address bar and add it to your OAuth provider's allow-list.