◉CLAUDE LABJP
●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API●CC 2.1.330 — Claude Code 2.1.330 fixes the multi-minute freeze right after compacting a long conversation●SONNET 4.5 — Sonnet 4.5 retires from the Claude API on 11/30, 8 days left. The suggested replacement is claude-sonnet-5-5●MCP 401 — Users report MCP servers that return 401 time out silently instead of showing an error●NEW — New: Desktop creates a worktree for every session? Three places to check●OPUS 4.5 — The 11/24 date for Opus 4.5 is a not-sooner-than floor, not a retirement notice●SCHEMA — Same schema, different shape: compare structured output from the Agent SDK and the Messages API
Articles/Claude Code
⟐ Claude Code/2026-11-22Intermediate

When a Remote MCP Server Goes Silent After Its Token Expires, Check for mcp-remote First

A remote MCP tool call hangs with no error. How to tell an expired token from a slow tool, a script that finds servers bridged through mcp-remote, and how to switch to the native HTTP transport or cap the wait.

Claude Code291MCP63OAuth5Troubleshooting29mcp-remote

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:

  1. The same tool was answering in seconds a moment ago. The silence begins right after the access token expires.
  2. 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.
  3. 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 connectedRefresh token availableRefresh also refused
Directly via claude mcp add --transport httpRefreshes in the background and resends; a normal result about 20 ms laterFails in roughly 0.6 s with "sign in again"
stdio server running npx mcp-remoteReturns normally if the refresh succeedsThe 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 user

Then 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:

  1. Run claude mcp list and look for ! Needs authentication.
  2. If it's there, sign in again via /mcp, then repeat the same action one call at a time and see whether it reproduces.
  3. 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.

Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

⟐ Claude Code2026-10-23
When a Nightly claude -p Says MCP "Needs Authentication": Check Mac Sleep and the Keychain First
If an unattended claude -p run leaves "needs authentication" or MCP timeouts in the morning log, check whether the Mac slept or the login keychain was locked. What v2.1.307 changed, and what it still leaves to you.
⟐ Claude Code2026-09-04
The ~/.claude.json Rollback Is Fixed in v2.1.259. Putting Back What It Erased Is Still Your Job
Concurrent sessions used to silently roll back each other's ~/.claude.json changes. v2.1.259 fixed that, but nothing restores the trust settings and MCP servers you already lost. Here is how I find and rebuild them, with a small key-path diff script.
⟐ Claude Code2026-11-21
When Every New Desktop Session Creates a Worktree: Three Places to Check, and When It's Fine to Turn It Off
Claude Code Desktop keeps creating a worktree for every new session, and .claude/worktrees/ and claude/ branches pile up. Here is where the Worktree default actually gets turned on, when to keep it and when to skip it, and a SessionStart hook that tells you when a session is running inside a worktree.