リモート MCP サーバーに接続する¶

ゴール：リモートの HTTP MCP サーバーを、あたかもローカルサーバーのように Claude Desktop / Claude Code に登場させる——ログインは処理済み、トークンは自動更新、トランスポートの癖は吸収済みの状態で。

1. まず接続確認¶

クライアント設定を触る前に、mcp-stdio がサーバーに届くことを確認します：

mcp-stdio --check --oauth https://mcp.example.com/mcp

--check は経路全体を一度だけ実行します——ディスカバリ、ブラウザでの OAuth ログイン、トークン交換、MCP initialize の往復——そして結果を表示します。これが成功すれば、以下のクライアント設定も動きます。

サーバーに OAuth がない場合は --oauth を外します。静的トークンなら MCP_BEARER_TOKEN を使います（下の「バリエーション」表を参照）。

2. クライアントに追加¶

Claude DesktopClaude Code

claude_desktop_config.json：

{
  "mcpServers": {
    "my-remote-server": {
      "command": "mcp-stdio",
      "args": ["--oauth", "https://mcp.example.com/mcp"]
    }
  }
}

claude mcp add my-remote-server -- mcp-stdio --oauth https://mcp.example.com/mcp

クライアントを再起動します。最初のリクエストでブラウザが開いてサーバーのログインページが表示されます。以後トークンは ~/.config/mcp-stdio/tokens.json（パーミッション 0600）に保存され、すべてのターミナル・セッションで共有されます——refresh トークン自体が失効・破棄されるまで再ログインは不要です。

何もしなくても付いてくるもの¶

自動トークンリフレッシュ — 401 で即時に、加えて失効直前にバックグラウンドで先回りして更新。長いセッションがアクセストークンの TTL で死にません。
セッション回復 — 失効した MCP セッション（404）は透過的に再初期化されます。
クライアントのバグの遮蔽 — キャンセル競合、ページネーション、 Retry-After など、実装間のギャップは中間で吸収されます。カタログは WORKAROUNDS へ。

バリエーション¶

こうしたい	こうする
OAuth なし、静的 Bearer トークン	`MCP_BEARER_TOKEN=… mcp-stdio https://…/mcp`
スコープを追加したい	`--oauth-scope "openid offline_access mcp:tools"`
このマシンにブラウザがない（SSH 先、コンテナ）	`--oauth-device` — ヘッドレスログインを参照
サーバーが OIDC の `id_token` を要求する（Google IAP、AWS）	`--oauth-use-id-token`
legacy SSE サーバー（2024-11-05 トランスポート）	`--transport sse`
社内プロキシ	標準の `HTTPS_PROXY` / `NO_PROXY` 環境変数がそのまま効きます

全フラグは mcp-stdio --help か README へ。

トラブルシュートの早見¶

ブラウザが開かない — authorize URL は stderr に出力されています。手動で開いてください（クライアントの MCP ログに出ます）。
Microsoft Entra ID で AADSTS9010010 — 一部の Entra ID 構成は resource パラメータそのものを拒否します。--no-resource-indicator を追加してください。詳細はトラブルシューティングを参照。
昨日まで動いていたのに今日は 401 — サーバー側で鍵のローテートやグラントの失効があったかもしれません。~/.config/mcp-stdio/tokens.json から該当サーバーのエントリを消して、再認可させてください。