日曜の昼、Claude Code の Issue を眺めていて、「401 を返しているのにエラーにならず、ツール呼び出しが黙って止まる」という報告に手が止まりました。リモートの MCP サーバーを OAuth でつないでいる方なら、一度は見たことのある症状だと思います。
私が最初に考えたのは「どうせ 120 秒で切れるのだろう」ということでした。報告の本文にそう書かれていたからです。ところがスレッドを読み進めると、検証した方のコメントでは、既定のままでは 30 分(1800 秒) 待ってからやっと打ち切られていました。思い込みで「2 分待てば分かる」と構えていたら、昼休みが丸ごと消えるところでした。
しかも、止まるかどうかは Claude Code 本体ではなく、サーバーをどうつないでいるかで決まっていました。症状の見分け方から、原因の切り分け、直し方、直らないときの次の一手まで、順にお伝えします。
症状の見分け方 — 「重い処理」と「認証切れ」を分ける3つの手がかり
ツールが返ってこないとき、まず疑うのはサーバー側の処理の重さです。けれども認証切れで止まっている場合は、次の3点が揃います。
- さっきまで同じツールが数秒で返っていました。アクセストークンの有効期限が切れた直後から、急に返らなくなります。
- 画面にエラーが一切出ません。直接つないだ HTTP 接続で認証が切れた場合は、すぐに
needs you to sign in again (run /mcp to re-authenticate)という文言が出ます。何も出ないこと自体が手がかりです。 - ブラウザに見慣れないサインインのタブが開いています。後で触れる mcp-remote は、認証が要ると自分でブラウザを開きます。デスクトップの奥に隠れていることがあります。
もう一つ、別のターミナルで claude mcp list を打つと、直接接続のサーバーなら ! Needs authentication と表示されます。mcp-remote 経由だとここは「接続済み」のままに見えることがあるので、表示が正常でも安心はできません。
原因 — 401 がどこで受け止められているか
Issue のスレッドでは、同じテスト用サーバーに二通りの方法でつないで比べた結果が報告されています(Claude Code 2.1.323、mcp-remote 0.16.6)。整理すると次のとおりです。
| つなぎ方 | リフレッシュトークンあり | リフレッシュも拒否された場合 |
|---|---|---|
claude mcp add --transport http で直接 | 裏で更新して再送。約 20 ms 後に普通に結果が返る | 約 0.6 秒で「sign in again」のエラー |
stdio で npx mcp-remote を挟む | 更新できれば、通常どおり結果が返る | 呼び出しが保留されたまま。既定では 1800 秒後に打ち切り |
mcp-remote を挟むと、Claude Code から見えるのは「手元で動いている stdio のサーバー」だけになります。401 を受け取るのは mcp-remote で、その mcp-remote はサインインをやり直そうとしたまま、保留中の呼び出しに返事をしません。Claude Code には「まだ処理中」にしか見えないのです。
黙っているのは Claude Code ではなく、間に挟んだ橋渡し役でした。 私自身、ずっと本体の不具合だと決めつけて読んでいたので、ここに気づいたのはスレッドの後半に差しかかってからでした。分かってしまえば、直す場所もはっきりします。
自分の設定を棚卸しする
どのサーバーが mcp-remote 経由なのかは、設定ファイルを開けば分かります。ただ、ユーザー単位の ~/.claude.json、プロジェクト単位の .mcp.json、ローカル単位(~/.claude.json の projects 配下)と置き場所が散っているので、私は一度に並べるスクリプトを書きました。
何を解決するかというと、「どのスコープの、どの名前のサーバーが、どの方式でつながっているか」を一覧にし、mcp-remote 経由のものに印を付けることです。
#!/usr/bin/env python3
"""MCP サーバーの接続方式を棚卸しし、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}: 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 (環境変数)"
return "未設定"
rows = collect()
if not rows:
print("MCP サーバーの設定が見つかりませんでした。")
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"mcp-remote 経由: {bridged} 件。認証切れで応答が返らず待ち続ける経路です。")
sys.exit(1)
print("mcp-remote 経由のサーバーはありません。")プロジェクトのフォルダで python3 find_bridged_mcp.py . と実行します。HTTP・SSE・stdio・mcp-remote を混ぜた見本の設定で試すと、出力は次のようになりました。
!! 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: 未設定
mcp-remote 経由: 1 件。認証切れで応答が返らず待ち続ける経路です。なぜこう書くかというと、type を持たない設定は stdio として扱われるため、command と args を連結して「mcp-remote」の文字列を探すのがいちばん取りこぼしが少ないからです。npx -y mcp-remote でも、グローバルに入れた mcp-remote でも拾えます。終了コードを 1 にしているのは、朝の点検スクリプトに組み込んだとき、印の付いた行があれば気づけるようにするためです。
直し方 — 直接接続へ切り替え、当面は待ち時間に上限をかける
1. 直接の HTTP 接続へ切り替える
印の付いたサーバーの URL を使って、つなぎ直します。スコープは元の設定に合わせてください。
# 例: ユーザー単位の tickets を張り替える
claude mcp remove tickets -s user
claude mcp add --transport http tickets https://mcp.example.com/mcp -s user追加したら Claude Code の中で /mcp を開き、該当サーバーの認証を済ませます。これで認証が切れたときも、黙って待たされることはなくなり、すぐに「sign in again」と言ってもらえます。
2. すぐに切り替えられない場合は、MCP_TOOL_TIMEOUT を置く
社内の事情で mcp-remote を外せないこともあると思います。その場合は、ツール呼び出しの待ち時間に上限をかけます。~/.claude/settings.json の env に書くのが手軽です。
{
"env": {
"MCP_TOOL_TIMEOUT": "120000"
}
}単位はミリ秒です。スレッドの検証では 10000 にすると 10 秒でツールのエラーとして返ってきていました。私は、手元でいちばん長くかかる正当な呼び出しより少し長い値にしています。短すぎると、重いだけの処理まで打ち切ってしまうからです。
ひとつ注意があります。打ち切りのときに Claude Code が送る取り消しの通知も、mcp-remote 側でまた 401 になり、サインインのタブがもう一枚開くことが報告されています。上限は「早く失敗させる」ための応急処置で、直すのは接続方式のほうです。 この線引きだけは守るようにしています。
直らないときの次の一手
直接接続に切り替えても「sign in again」が何度も出る場合は、同時に複数のツールを呼んだときのトークン更新を疑います。スレッドでは、読み取り専用の呼び出しが 3 本同時に走ったとき、更新要求が 5 回飛び、リフレッシュトークンを使い回すと失効させる設定のサーバーでは、保存していたトークンが空になったと報告されています——1 回の期限切れで、サインインまでやり直しになるわけです。
この場合は、次の順で確かめていただければと思います。
claude mcp listで! Needs authenticationが出ているかを見ます- 出ていたら
/mcpでサインインし直し、同じ操作を「1 本ずつ」呼んで再現するかを見ます - 1 本ずつなら通る場合は、サーバー側のリフレッシュトークンのローテーション設定を管理者に確認します
ヘッダーで認証を渡す構成に移した場合の別の落とし穴は、headersHelper に移したらプロジェクト配下だけ認証が通らなくなった記録にまとめています。サーバーが増えてきて、起動直後の一覧そのものを疑いたくなった方には、起動直後の MCP 一覧を確かめ直す仕組みが、もう一段深い手当てになるはずです。
まずは今日、棚卸しのスクリプトを一度だけ走らせて、印の付いた行があるかどうかを見てみてください。1 行もなければ、それがいちばんの安心材料になります。