Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

複数のClaude Codeインスタンスを同時に実行した際のMCP OAuthトークンリフレッシュの競合状態を修正しました。

原文（英語） ​

Fixed MCP OAuth token refresh race condition when running multiple Claude Code instances simultaneously

概要 ​

複数のClaude Codeインスタンスを同時に実行している環境で発生していたMCP（Model Context Protocol）のOAuthトークンリフレッシュに関する競合状態（レースコンディション）が修正されました。従来は、複数のインスタンスが同時にOAuthトークンのリフレッシュを試みると、一方のインスタンスが古いトークンで認証に失敗し、再認証が必要になるという問題がありました。この修正により、複数のClaude Codeインスタンスを並行して使用する際の安定性が大幅に向上します。

基本的な使い方 ​

影響を受けていたシナリオ ​

この修正は特に以下の環境で効果があります：

bash
# ターミナル1: Claude Codeセッション1
claude

# ターミナル2: 同時に別のClaude Codeセッション
claude

# 以前はこの同時起動で、どちらかのセッションが
# OAuthトークンリフレッシュ時に認証エラーを起こす場合があった

MCPサーバーとの接続確認 ​

bash
# MCP接続状態の確認
/mcp

# MCP再接続（必要な場合）
/mcp reconnect

実践例 ​

複数の並行CI/CDジョブでの使用 ​

bash
# 並行して実行されるCIジョブでの使用例
# job1.sh
claude --headless -p "テストを実行してください" --output-format json

# job2.sh（同時実行）
claude --headless -p "ビルドを確認してください" --output-format json

# 改善前: どちらかのジョブがOAuth認証エラーで失敗する可能性があった
# 改善後: 並行実行でも安定して動作する

マルチウィンドウ開発ワークフロー ​

bash
# 複数のプロジェクトで同時にClaude Codeを使用
# プロジェクトA のディレクトリでClaude Codeを起動
cd ~/projects/project-a && claude

# 別のターミナルでプロジェクトBでも起動
cd ~/projects/project-b && claude

# 改善後: 両方のセッションが独立して安定動作
# 一方がトークンリフレッシュしても他方に影響しない

headlessモードでの自動化スクリプト ​

bash
#!/bin/bash
# 複数のhttpMCPサーバーを使う自動化スクリプト

# OAuthで認証されたMCPサーバーに接続する複数の並行タスク
claude --headless -p "GitHub MCP経由でIssueを確認" &
PID1=$!

claude --headless -p "Slack MCP経由でメッセージを送信" &
PID2=$!

wait $PID1 $PID2
# 改善後: 両タスクが安定して完了する

MCP OAuth設定の確認 ​

bash
# MCPサーバーにOAuth認証情報を事前設定する場合
claude mcp add my-server https://api.example.com \
  --transport http \
  --client-id "your-client-id" \
  --client-secret "your-client-secret"

技術的な背景 ​

この問題は、OAuthリフレッシュトークンがシングルユース（1回限り有効）であることに起因していました：

  1. 複数のClaude Codeインスタンスが同時にトークンリフレッシュを試みる
  2. 最初のインスタンスが成功し、新しいリフレッシュトークンを取得
  3. 2番目のインスタンスは既に無効になった古いトークンで試み、404エラーが発生
  4. 2番目のインスタンスが認証失敗状態に陥る

修正後は、トークンリフレッシュの競合を適切に処理し、いずれかのインスタンスが成功した場合に新しいトークンが共有されるようになりました。

注意点 ​

  • この修正により、複数の同時セッションでの再認証を求められるケースが大幅に減少します
  • それでも稀に認証エラーが発生する場合は、/mcp reconnect コマンドで再接続を試みてください
  • 根本的な回避策として ANTHROPIC_API_KEY 環境変数を設定することでOAuthをバイパスすることも可能ですが、これはサブスクリプション利用ではなくAPIの従量課金が適用されます
  • headlessモードや非対話型環境での長時間実行でのトークン期限切れ問題は、今回の修正で大幅に改善されています

関連情報 ​