On a quiet Sunday afternoon I was skimming the Claude Code issue tracker when one report stopped me: a remote MCP server returns 401, yet nothing surfaces as an error, and the tool call just sits there. If you connect remote MCP servers over OAuth, you have probably watched that spinner yourself.
My first assumption was that it would give up after 120 seconds, because that is what the report said. Reading further down the thread, though, someone who reproduced it carefully found that with default settings Claude Code waits a full 30 minutes (1800 seconds) before aborting. Had I gone in expecting a two-minute wait, I would have lost an entire lunch break staring at it.
More importantly, whether it hangs at all depends less on Claude Code and more on how the server is wired in. Here is how I would tell the symptoms apart, narrow down the cause, fix it, and what to try if the fix doesn't stick.
Telling "slow tool" apart from "expired token"
When a tool doesn't come back, the natural suspect is a heavy job on the server. An expired token, however, tends to show three things at once:
- The same tool was answering in seconds a moment ago. The silence begins right after the access token expires.
- No error appears anywhere. On a direct HTTP connection, an expired session immediately prints
needs you to sign in again (run /mcp to re-authenticate). Silence is itself the clue. - There's an unfamiliar sign-in tab in your browser. mcp-remote, which I'll get to shortly, opens a browser window on its own when it wants you to re-authenticate. It often hides behind other windows.
One more check: run claude mcp list in another terminal. A directly connected server will show ! Needs authentication. A server behind mcp-remote may still look connected, so a clean list isn't proof that everything is fine.
The cause: who actually receives the 401
People in the issue thread connected the same test server two ways and compared the results (Claude Code 2.1.323, mcp-remote 0.16.6). Condensed:
| How it's connected | Refresh token available | Refresh also refused |
|---|---|---|
Directly via claude mcp add --transport http | Refreshes in the background and resends; a normal result about 20 ms later | Fails in roughly 0.6 s with "sign in again" |
stdio server running npx mcp-remote | Returns normally if the refresh succeeds | The call is held indefinitely; aborted after 1800 s by default |
With mcp-remote in the middle, all Claude Code can see is a local stdio server. The 401 lands on mcp-remote, which starts its own sign-in flow and never answers the request it is holding. From Claude Code's side, the tool simply looks busy.
It wasn't Claude Code that went quiet; it was the bridge in between. Once that clicks, the place to fix it becomes obvious.
Taking inventory of your own config
You can see which servers go through mcp-remote by opening your config files, but they're spread out: user scope in ~/.claude.json, project scope in .mcp.json, and local scope under the projects key inside ~/.claude.json. I wanted them in one list, so I wrote a short script.
The problem it solves: list every server by scope, name, and transport, and flag the ones bridged through mcp-remote.
#!/usr/bin/env python3
"""Inventory MCP server transports and flag servers bridged through mcp-remote."""
import json
import os
import sys
from pathlib import Path
HOME = Path(os.environ.get("HOME", "~")).expanduser()
PROJECT = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
def load(path: Path):
try:
return json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError:
return {}
except json.JSONDecodeError as e:
print(f"[skip] {path}: not valid JSON ({e})")
return {}
def collect():
rows = []
user = load(HOME / ".claude.json")
for name, cfg in (user.get("mcpServers") or {}).items():
rows.append(("user", name, cfg))
local = (user.get("projects") or {}).get(str(PROJECT), {})
for name, cfg in (local.get("mcpServers") or {}).items():
rows.append(("local", name, cfg))
shared = load(PROJECT / ".mcp.json")
for name, cfg in (shared.get("mcpServers") or {}).items():
rows.append(("project", name, cfg))
return rows
def classify(cfg: dict):
kind = cfg.get("type", "stdio")
if kind in ("http", "sse"):
return kind, cfg.get("url", "")
args = [str(a) for a in cfg.get("args", [])]
joined = " ".join([str(cfg.get("command", ""))] + args)
if "mcp-remote" in joined:
url = next((a for a in args if a.startswith("http")), "")
return "stdio+mcp-remote", url
return "stdio", ""
def tool_timeout():
for p in (HOME / ".claude" / "settings.json", PROJECT / ".claude" / "settings.json"):
env = load(p).get("env") or {}
if "MCP_TOOL_TIMEOUT" in env:
return f"{env['MCP_TOOL_TIMEOUT']} ms ({p})"
if os.environ.get("MCP_TOOL_TIMEOUT"):
return f"{os.environ['MCP_TOOL_TIMEOUT']} ms (environment)"
return "not set"
rows = collect()
if not rows:
print("No MCP server configuration found.")
sys.exit(0)
bridged = 0
for scope, name, cfg in rows:
kind, url = classify(cfg)
mark = "!!" if kind == "stdio+mcp-remote" else " "
bridged += kind == "stdio+mcp-remote"
print(f"{mark} {scope:<8} {name:<20} {kind:<18} {url}")
print(f"\nMCP_TOOL_TIMEOUT: {tool_timeout()}")
if bridged:
print(f"Bridged through mcp-remote: {bridged}. These can hang silently when auth expires.")
sys.exit(1)
print("No servers bridged through mcp-remote.")Run it from your project folder with python3 find_bridged_mcp.py .. Against a sample config mixing HTTP, SSE, plain stdio, and mcp-remote, the output looked like this:
!! user tickets stdio+mcp-remote https://mcp.example.com/mcp
user notes http https://notes.example.com/mcp
local localfs stdio
project docs sse https://docs.example.com/sse
MCP_TOOL_TIMEOUT: not set
Bridged through mcp-remote: 1. These can hang silently when auth expires.Why it's written this way: an entry with no type is treated as stdio, so joining command and args and searching for "mcp-remote" is the least leaky test. It catches npx -y mcp-remote and a globally installed mcp-remote alike. The exit code of 1 is there so that, as an indie developer who runs a small morning check script, I notice a flagged line without having to read the whole output.
The fix: connect directly, and cap the wait in the meantime
1. Switch to the native HTTP transport
Reconnect each flagged server using its URL. Keep the same scope it had before.
# Example: re-add the user-scoped "tickets" server
claude mcp remove tickets -s user
claude mcp add --transport http tickets https://mcp.example.com/mcp -s userThen open /mcp inside Claude Code and complete sign-in for that server. From now on, an expired session tells you "sign in again" right away instead of leaving you waiting.
2. If you can't switch yet, set MCP_TOOL_TIMEOUT
Sometimes mcp-remote has to stay for organizational reasons. In that case, put an upper bound on how long a tool call may take. The env block in ~/.claude/settings.json is the easiest place:
{
"env": {
"MCP_TOOL_TIMEOUT": "120000"
}
}The value is in milliseconds. In the thread, setting it to 10000 turned the hang into a tool error after 10 seconds. I'd pick something a little longer than the slowest legitimate call you have; go too short and you'll cut off tools that are merely slow.
One caveat. When the timeout fires, Claude Code sends a cancellation notice, and mcp-remote hits a 401 on that too, which was reported to open yet another sign-in tab. The timeout is a way to fail fast; the actual fix is the transport. That's the line I'd hold.
If it still doesn't settle
If you've switched to the direct connection and still keep seeing "sign in again," suspect token refresh under concurrent calls. The thread reports that three read-only calls running at once produced five refresh requests, and on a server that revokes on refresh-token reuse, the stored tokens ended up empty. In other words, one expired access token can cost you a full sign-in.
I'd check it in this order:
- Run
claude mcp listand look for! Needs authentication. - If it's there, sign in again via
/mcp, then repeat the same action one call at a time and see whether it reproduces. - If single calls are fine, ask whoever runs the server about its refresh-token rotation policy.
If you've moved credentials into headers instead, I wrote up a different pitfall in the headersHelper change that broke auth only for project-scoped catalogs. And if your server list has grown to the point where you no longer trust what it shows right after startup, re-checking the MCP list right after startup goes one step deeper.
For today, I'd run the inventory script once and see whether anything gets flagged. If nothing does, that alone is worth knowing.