MCP を使用して Claude Code をツールに接続する

​

MCP でできること

• 課題追跡ツールから機能を実装する：「JIRA の課題 ENG-4521 に記載されている機能を追加し、GitHub に PR を作成してください。」
• 監視データを分析する：「Sentry と Statsig をチェックして、ENG-4521 に記載されている機能の使用状況を確認してください。」
• データベースをクエリする：「PostgreSQL データベースに基づいて、ENG-4521 機能を使用した 10 人のランダムなユーザーのメールアドレスを検索してください。」
• デザインを統合する：「Slack に投稿された新しい Figma デザインに基づいて、標準メールテンプレートを更新してください。」
• ワークフローを自動化する：「新機能に関するフィードバックセッションに招待する 10 人のユーザーに Gmail ドラフトを作成してください。」
• 外部イベントに対応する：MCP サーバーは チャネル として機能することもでき、セッションにメッセージをプッシュするため、Claude は離席中に Telegram メッセージ、Discord チャット、または webhook イベントに対応できます。

​

MCP サーバーを検索してビルドする

/plugin install mcp-server-dev@claude-plugins-official

/mcp-server-dev:build-mcp-server

​

MCP サーバーのインストール

​

オプション 1: リモート HTTP サーバーを追加する

# 基本的な構文
claude mcp add --transport http <name> <url>

# 実際の例: Notion に接続
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Bearer トークン付きの例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

​

オプション 2: リモート SSE サーバーを追加する

# 基本的な構文
claude mcp add --transport sse <name> <url>

# 実際の例: Asana に接続
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 認証ヘッダー付きの例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

​

オプション 3: ローカル stdio サーバーを追加する

# 基本的な構文
claude mcp add [options] <name> -- <command> [args...]

# 実際の例: Airtable サーバーを追加
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

​

Claude Code が stdio サーバーを停止する方法

• macOS と Linux: Claude Code は SIGINT を送信し、100 ミリ秒後もプロセスが実行中であれば SIGTERM を、さらに 400 ミリ秒後に SIGKILL を送信します。
• Windows: Claude Code はサーバーの stdin を閉じ、300 ミリ秒後もプロセスが実行中であればサーバーのプロセスツリーを終了します。

​

オプション 4: リモート WebSocket サーバーを追加する

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

​

別のクライアント向けに書かれたセットアップ指示からサーバーを追加する

• URL（https://mcp.example.com/mcp など）: サーバーはリモートです。
• 起動コマンド（npx -y @example/mcp-server など）: サーバーはマシン上で実行されます。
• mcpServers JSON ブロック: 別のクライアントの設定ファイル向けに書かれた設定。

​

URL からサーバーを追加する

claude mcp add --transport http example https://mcp.example.com/mcp

​

npx、uvx、またはバイナリコマンドからサーバーを追加する

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

​

mcpServers JSON ブロックからサーバーを追加する

• type のない url: エンドポイントに一致するように "type": "http"、"type": "sse"、または "type": "ws" を追加してください。Claude Code は type を持たないエントリを stdio サーバーとして読み込むため、type のない url エントリは失敗します。
• 文字、数字、ハイフン、アンダースコア以外の文字を持つキー: これらの文字のみを使用するサーバー名を選択してください。そうでない場合、キーはサーバー名です。

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

​

サーバーの管理

# すべての設定されたサーバーをリストする
claude mcp list

# 特定のサーバーの詳細を取得する
claude mcp get notion

# サーバーを削除する
claude mcp remove notion

# （Claude Code 内）サーバーステータスを確認する
/mcp

​

サーバーステータス

• ⏸ Pending approval (run `claude` to approve): まだ承認していない .mcp.json のプロジェクトスコープのサーバーです。Claude Code は claude mcp list と claude mcp get <name> の両方にこれを表示します。claude を対話的に実行して確認し、承認してください。
• ✘ Rejected (see disabledMcpjsonServers in settings): disabledMcpjsonServers エントリが拒否する .mcp.json サーバー。Claude Code はそれを claude mcp get <name> にのみ表示します。
• ⊘ Disabled for this project (re-enable via /mcp): プロジェクトの disabledMcpServers リストが名前を付けるサーバー。Claude Code はそれを claude mcp list と claude mcp get <name> の両方に表示します。/mcp パネルからサーバーをオンに戻してください。
• ✘ Blocked by enterprise managed policy: 組織のポリシーのいずれかによって拒否されたサーバーです。Claude Code は claude mcp list と claude mcp get <name> の両方にこれを表示します。管理 MCP 設定の許可リスト、拒否リスト、またはその他の制限によってブロックされたサーバーは、このステータスで表示されるのではなく、両方のコマンドから非表示になります。どのポリシーがサーバーをブロックしているかは管理者に確認してください。

​

プロジェクトサーバーの承認とワークスペーストラスト

• ユーザー ~/.claude/settings.json
• 管理設定
• --settings で渡された設定

​

サーバーステータスの詳細

• パスとクエリはそのメッセージに表示されません。
• ローカル、プロジェクト、またはユーザー スコープ のサーバー、または管理 MCP 設定のサーバーの場合、��リジンはその設定に書かれたとおりのホストを表示するため、ホストの ${VAR} 参照はメッセージで展開されません。
• ステータスまたはエラーコードのない失敗の場合、Claude Code はオリジンなしでエラーテキストを表示します。

​

設定警告

• 隠れた空白: Claude Code は MCP 設定値が隠れた先頭または末尾の空白を持つときに警告します。これはしばしば末尾の改行を持つトークンを貼り付けることから来ます。Claude Code は command、url、各 args エントリ、および env と headers の下の値とキー名をチェックします。Claude Code は警告を claude mcp list 出力と /mcp に表示し、値を表示せずに影響を受けたフィールドの名前を示します。例えば Leading or trailing whitespace in: headers.Authorization。Claude Code は空白をトリムせず、書かれたとおりに値を使用するため、設定を編集してそれを削除してください。
• 複数のスコープで同じ名前: 異なるエンドポイントで複数の スコープ で同じサーバー名を定義する場合、Claude Code は claude mcp list 出力と /mcp で競合について警告します。Claude Code は OAuth サインインをエンドポイントごとに保存するため、1 つのプロジェクトで読み込まれる定義を認証しても、別の定義が読み込まれるプロジェクトでは別にサインインする必要があります。必要なエンドポイントを保持し、他を claude mcp remove <name> --scope <scope> で削除してください。警告では、Claude Code は各スコープのエンドポイントを設定に書かれたとおりに、${VAR} 参照 を展開せずに引用するため、API キーなどの解決された値を表示することはありません。
• 予約名: Claude Code は workspace、claude-in-chrome、computer-use、Claude Preview、Claude Browser を含む組み込みサーバーの名前を予約しています。設定が予約名を持つサーバーを定義する場合、Claude Code はロード時にそれをスキップし、名前を変更するよう求める警告を表示します。claude mcp add は予約名をエラーで拒否します。Claude Preview と Claude Browser はどちらも Claude Code デスクトップアプリのプレビューペイン が使用する組み込みサーバーの名前です。
• 環境変数の欠落: サーバーの設定の ${VAR} 参照 が設定されていない変数を指し、:-default がない場合、Claude Code は claude mcp list 出力と /mcp でその変数名を示して警告し、${VAR} テキストを展開しないままサーバーを読み込みます。変数を設定するか、${VAR:-default} フォールバックを追加してください。リモートサーバーの url と headers では、一部の認証情報変数は代わりに警告なしで 空として読み込まれます。

​

ツール可用性

• ツール検索（デフォルト）を使用: 待機は ToolSearch 呼び出し内で発生します。
• ツール検索なし: Claude は代わりに WaitForMcpServers ツールを使用します。ツール検索なしの設定には、ENABLE_TOOL_SEARCH=false と、Google Cloud の Agent Platform 上の Claude Opus 4.5、Claude Sonnet 4.5、Claude Haiku 4.5 より前のモデルが含まれます。ANTHROPIC_BASE_URL ゲートウェイについては、LLM ゲートウェイ経由のツール検索 を参照してください。
• Microsoft Foundry の Azure でホストされたデプロイ: Claude Code はデプロイのサーバー側の拒否を API からしか検出できないため、Claude は WaitForMcpServers ではなくツール検索パスで開始します。Claude Code がそのデプロイを 事前読み込み に切り替えた後は、接続を完了したサーバーのツールが Claude の次のリクエストで利用可能になります。

​

サーバーを削除せずに無効にする

• disabledMcpServers: ユーザー設定サーバー、プラグインサーバー、組織が 管理設定を通じて提供 するサーバー、Claude Code が 自身で取得 する claude.ai コネクタ、およびデフォルトでオンの組み込みサーバーのオプトアウトリスト。Claude Code はここにリストするサーバーに接続しません。Disable claude.ai connectors で説明されているプロジェクトごとの /mcp トグルで claude.ai コネクタを無効にすると、Claude Code はそれをこのリストの下に表示名で書き込みます。例えば claude.ai Slack。
• enabledMcpServers: computer-use などのデフォルトでオフの組み込みサーバーのオプトインリスト。Claude Code はここにリストする場合にのみデフォルトオフサーバーに接続します。

​

MCP クライアントランタイム

• Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry のセッション。ただし、Claude Code を埋め込むホストプラットフォームが CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定する場合を除きます
• Claude apps gateway を通じてサインインしたセッション
• テレメトリまたはフィーチャーフラグ取得をオフにしたセッション。例えば DISABLE_TELEMETRY を使用

• HTTP、stdio、claude.ai コネクタの各サーバーに新しいリビジョンをサポートするかどうかを尋ね、それをサポートするサーバーで使用します。これには、クラウドセッションと Remote Control セッションのコネクタも含まれます。他のすべてのサーバーには v1 と同様に接続します。
• 新しいリビジョンのサーバーから 保持するストリーム 上で list_changed 通知を受け取ります。
• 新しいリビジョンで接続する チャネル サーバーを登録しません。そのリビジョンはチャネルメッセージを運ぶことができないためです。
• 予期しない発行者を示す認可応答の MCP OAuth サインイン を失敗させます。
• MCP OAuth 認証情報を HTTPS でサービスされるトークンエンドポイント、または localhost、127.0.0.1、::1 でのみ送信します。別の場所（ローカルネッ���ワーク上のデバイスなど）で平文 http:// のトークンエンドポイントを持つサーバーのサインインは失敗します。Refusing to send credentials to non-https token endpoint を参照してください。

​

動的ツール更新

• 対話的なターミナルセッションでは、Claude Code はそのサーバーから更新されたリストを取得するため、再接続する必要はありません。
• -p フラグを使用した 非対話モード および Agent SDK では、Claude Code はこれらの通知に対してツールリストのみをリフレッシュします。

​

v2 ランタイムの通知ストリーム

• ストリームが 10 秒以内に再度閉じる: Claude Code はそれを最大 3 回再度開き、その接続に対して停止します。
• ストリームが 10 秒以上開いたままで、その後閉じる（サーバーレスホストへのストリームでよく起こります）: 1 時間に 5 回再度開いた後、Claude Code は次に再度開くまで約 6 時間待機します。

​

自動再接続

​

リモートサーバーのセッション中のドロップ

• 対話的セッション: /mcp は Claude Code が再接続している間、サーバーを保留中として表示します。5 回の試行に失敗した後、Claude Code はサーバーを失敗としてマークするか、サーバーの再認可が必要な場合は認証が必要としてマークします。サーバーを失敗としてマークすると、MCP server "<name>" disconnected · open /mcp to reconnect 通知が表示されます。/mcp から手動で再試行できます。
• claude -p 実行と Agent SDK セッション: Claude Code は同じ 5 回の試行を行いますが、それを表示する /mcp パネルはありません。5 回すべてが失敗した場合、実行はサーバーのツールなしで続行されます。
  • 5xx レスポンスやタイムアウトなどの一時的なエラーの後: Claude Code は HTTP または SSE サーバーの再試行をバックグラウンドで続けます。再試行は最大約 30 分間続き、接続するとサーバーのツールが再び利用可能になります。それまでの間、Agent SDK セッションは ステータス failed を報告し、コードから サーバーを再接続 できます。claude -p で再接続するには、実行をやり直してください。
  • サーバーが 再度サインインを必要とする 場合: Claude Code は再試行を停止し、Agent SDK セッションはサーバーのステータスを needs-auth として報告します。シェルで claude mcp login <name> を実行してサインインしてください。その後、実行をやり直すか、Agent SDK セッションでは代わりに サーバーを再接続 してください。

​

失敗した最初の接続

• stdio サーバーの最初の接続。再度試すには、終了した、または起動に失敗した stdio サーバー を参照してください
• WebSocket サーバーの最初の接続。対話的なターミナルセッションでもう一度試すには、/mcp でサーバーのメニューから Reconnect を選択してください
• 認証エラーまたは not-found エラー。解決には設定の変更が必要なためです。headersHelper がサーバーの Authorization ヘッダーの唯一のソースである場合は、Claude Code は認証エラーでも再試行します。各試行でヘルパーを再実行し、新しい認証情報を取得できるためです

​

終了した、または起動に失敗した stdio サーバー

​

失敗した検出リクエスト

​

失敗したサーバーを自分で再試行する

​

Claude がサーバーが失敗したことを学ぶ方法

• ツール検索を使用している場合、Claude Code は Claude にどのサーバーが失敗したか、その接続エラーを伝えるため、Claude は応答で接続失敗を報告します。Claude Code は一致するツールを見つけない ToolSearch 結果にも同じ情報を含めます。
• ツール検索なしの設定 では、Claude Code は失敗したサーバー接続を Claude に報告しません。

​

チャネルでメッセージをプッシュする

​

MCP ツール呼び出しの時間制限

• サーバーごと: そのサーバーの設定エントリにミリ秒単位の timeout フィールドを追加します
• サーバー全体: MCP_TOOL_TIMEOUT を設定します

​

長いツール呼び出しの自動バックグラウンド化

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 環境変数をミリ秒単位で設定してしきい値を変更するか、0 に設定して自動バックグラウンド化をオフにします。0 の場合、Claude は対話セッションで MCP タスクも待機します
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に設定すると、自動バックグラウンド化とバックグラウンドコマンドがオフになります

• サブエージェント からの呼び出し。Claude Code はメイン会話呼び出しのみをバックグラウンド化します
• IDE サーバーへの呼び出し
• 非対話モード での呼び出し。ただし CLAUDE_AUTO_BACKGROUND_TASKS が 1 に設定されている場合を除きます。1 回限りの実行は結果が到着する前に終了する可能性があるため

​

サーバー上で実行される MCP タスク

​

MCP タスクを停止する、または結果を取得する

MCP task <server task id> (<server>/<tool>) completed.

​

MCP タスクからの質問に答える

​

MCP タスクの実行中に終了、クリア、または再開する

​

呼び出しが MCP タスクになるための要件

• サーバーがタスクをサポートしている
• サーバーが、プロトコルリビジョン 2026-07-28 で接続された HTTP、stdio、または claude.ai コネクタのサーバーである。MCP_SDK_GENERATION=v1 または MCP_PROTOCOL_NEGOTIATION=legacy を設定すると、この条件は満たされなくなります
• セッションが機能フラグを取得する。したがって、Amazon Bedrock などのサードパーティプロバイダー上のセッションや、テレメトリまたはフラグ取得をオフにしたセッションは対象外です
• Anthropic がその種類のセッションで MCP タスクをオンにしている。v2.1.304 以降では、ターミナルの CLI セッション、Agent SDK セッション、GitHub Actions の実行が対象です。VS Code 拡張機能やデスクトップアプリなど、その他のサーフェスには MCP タスクはありません
• 呼び出しがサブエージェントからではなく、メインの会話から行われる
• セッションが対話型であるか、または Agent SDK セッション、もしくは --input-format stream-json を読み取る claude -p 実行で、次の条件を満たしている
  • CLAUDE_AUTO_BACKGROUND_TASKS が 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND が 1 ではない
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS が 0 ではない

​

MCP タスクのステータスメッセージ

​

MCP タスクの時間制限

​

Claude に MCP タスクの結果を待機させる

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS を 0 に設定: Claude はすべての MCP ツール呼び出しを、呼び出しが終了するまで待機します
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND を 1 に設定: Claude はタスクの結果を待機します。自動バックグラウンド化がオンの間は、デフォルトで 2 分後に呼び出しが移行されるため、短いタスクはその場で完了し、長いタスクがユーザーをブロックすることはありません。移行された呼び出しは MCP タスクではなく通常のバックグラウンド呼び出しであり、セッションを終了すると失われます

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

​

サーバー作成者向けの MCP タスク

​

タスクで呼び出しに応答する

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

​

ステータス、結果、質問を報告する

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

​

プラグイン提供の MCP サーバー

• プラグインはプラグインルートの .mcp.json または plugin.json にインラインで MCP サーバーを定義します
• プラグインを有効にすると、Claude Code は自動的にその MCP サーバーを起動します
• Claude Code は手動で設定された MCP ツールと並んでプラグイン MCP ツールを提供します
• プラグインサーバーの追加と削除は、/mcp コマンドではなく、プラグインのインストールまたはアンインストールで行います。それでも /mcp で インストールされたプラグインサーバーをオフに切り替える ことはでき、プラグインを削除せずに Claude Code がそれに接続するのを停止できます

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

• 自動ライフサイクル: サーバーはこれらのポイン���で接続および切断���れます。
  • セッション起動時、Claude Code は有効なプラグインのサーバーを自動的に接続します。/mcp では、以前使用したリモート（HTTP または SSE）プラグインサーバーは代わりに cached ステータス を表示できます。Claude Code は Claude が最初にそのツールの 1 つを呼び出すときに接続します。stdio プラグインサーバーの接続が 15 分以内に失敗していた場合、Claude Code は 接続をスキップします
  • セッション中にプラグインを有効または無効にする場合、Claude Code はその変更が適用されるときにその MCP サーバーを接続または切断します。それがいつかは プラグイン変更を再起動なしで適用 で説明しています。対話的なターミナルのないセッションでは、/reload-plugins はプラグイン MCP サーバーを接続または切断しません。これらの変更は次のセッションで有効になります
  • リロードするとき、Claude Code は設定が変更されていないプラグインサーバーのライブ接続を保持し、Agent SDK からそれらを指定せずに セッションの MCP サーバーリストを置き換える ときも同様です
  • v2.1.246 以降で /cd でセッションを移動する とき、Claude Code は新しいディレクトリの設定が有効にするプラグインのサーバーを接続し、有効でなくなったプラグインのサーバーを切断するため、移動後に /reload-plugins を実行する必要はありません
  • クラウドセッション では、まだ接続されていないプラグインサーバーへの MCP 呼び出し（アイドルセッションが起動した直後など）は、サーバーをオンデマンドで開始し、接続を待ちます
• パスプレースホルダー: ${CLAUDE_PLUGIN_ROOT} はプラグインのインストールディレクトリに解決され、${CLAUDE_PLUGIN_DATA} はその 永続状態 ディレクトリに解決され、${CLAUDE_PROJECT_DIR} は安定したプロジェクトルートに解決されます。置換は以下に適用されます。
  • stdio サーバー: command、args、env
  • http、sse、ws サーバー: url、headers、headersHelper
• ユーザー環境アクセス: 手動で設定されたサーバーと同じ環境変数へのアクセス
• 複数のトランスポートタイプ: stdio、SSE、HTTP、WebSocket トランスポートのサポート。ただし、トランスポートサポートはサーバーによって異なる場合があります

• stdio サーバー: Command: stdio、空の Args: ���、および各環境変���を NAME=[REDACTED] として出力します
• WebSocket サーバー: URL: ws と、各ヘッダーを <name>: [REDACTED] として出力し、claude mcp list は URL の代わりに ws を表示します

mcp__plugin_my-plugin_database-tools__query

​

MCP インストールスコープ

​

ローカルスコープ

# ローカルスコープのサーバーを追加する（デフォルト）
claude mcp add --transport http stripe https://mcp.stripe.com

# ローカルスコープを明示的に指定する
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

​

プロジェクトスコープ

# プロジェクトスコープのサーバーを追加する
claude mcp add --transport http shared-server --scope project https://example.com/mcp

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

• disabledMcpjsonServersに追加します。これはすべての権限モードでそれをブロックします。
• --setting-sourcesまたは SDK の settingSources オプションでプロジェクト設定全体を除外します。
• --strict-mcp-configでセッションを開始します。Claude Code は --mcp-config で渡した MCP サーバーのみを使用します。Claude Code がロードしていないプロジェクトスコープのサーバーの承認プロンプトをスキップするには、Claude Code v2.1.246 以降が必要です。v2.1.246 より前では、厳密なセッションでもそれらの承認を待機していたため、バックグラウンドセッションは起動時に待機していました。マネージド MCP ファイルの下でフラグが何をするかについては、マネージド mcp.json での排他的制御を参照してください。

​

ユーザースコープ

# ユーザーサーバーを追加する
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

​

スコープの階層と優先順位

1. ローカルスコープ
2. プロジェクトスコープ
3. ユーザースコープ
4. プラグイン提供サーバー
5. claude.ai コネクタ

​

.mcp.json での環境変数の展開

• ${VAR} - 環境変数 VAR の値に展開されます
• ${VAR:-default}：VAR が設定されている場合は VAR の値に、設定されていない場合は default に展開されます

​

変数展開を使用した例

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

​

デフォルトなしの未設定変数

​

空文字列に設定された変数

​

空として読み込まれる認証情報変数

• Claude Code 独自の認証情報（ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN など）
• クラウドプロバイダーの認証情報（AWS_BEARER_TOKEN_BEDROCK など）
• 環境が保持する他の認証情報（HTTPS_PROXY や NPM_TOKEN など）

​

/mcp と CLI 出力での参照の表示方法

• サーバーの /mcp 詳細ビューの URL またはコマンドライン
• claude mcp list と claude mcp get の出力

​

実践的な例

​

例：コードレビューのために GitHub に接続する

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

PR #456 をレビューして改善を提案してください

見つけたバグの新しい課題を作成してください

自分に割り当てられているすべてのオープン PR を表示してください

​

例：PostgreSQL データベースをクエリする

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

今月の総収益はいくらですか？

orders テーブルのスキーマを表示してください

過去 90 日間に購入していない顧客を検索してください

​

リモート MCP サーバーで認証する

• サインインしていないサーバーの場合、どちらのステータスコードでも /mcp でそのサーバーが警告表示されるため、OAuth フローを完了できます。
• claude.ai コネクタの場合、claude.ai がセッショントークンを拒否することによる 401 ではコネクタは警告表示されません。コネクタを再認可してもログインを修正できないためです。Claude Code は代わりにセッショントークン拒否状態を表示します。
• headers または headersHelper を通じて Authorization ヘッダーを設定したサーバーの場合、接続中の 401 または 403 ではサーバーは警告表示されません。修正すべき認証情報は設定した認証情報だからです。Claude Code は代わりに接続が失敗したことを報告します。そのヘッダーを ${VAR} 参照から設定している場合は、その変数が Claude Code が空として読み込む変数の 1 つであるかどうかを確認してください。
• クラウドセッションに配信されたコネクタの場合、Claude Code はサインインフローを実行しません。セッションのプロキシが claude.ai で付与した認可を使用してコネクタに認証するためです。そこでコネクタが再度認可を必要とする場合は、セッションからではなく claude.ai/customize/connectors で再接続してください。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

​

コマンドラインから認証する

claude mcp login sentry

claude mcp login sentry --no-browser

​

固定 OAuth コールバックポートを使用する

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

事前設定された OAuth 認証情報を使用する

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

OAuth メタデータ検出を上書きする

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

​

OAuth スコープを制限する

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

​

認証プロキシの背後にあるサーバーで OAuth を使用する

• プロキシのヘッダー：--header、headers フィールド、または headersHelper で、プロキシが読み取る名前で渡してください
• OAuth サインイン：設定するヘッダーに Authorization を含めず、シェルで claude mcp login <name> を実行してサインインしてください。Authorization ヘッダーを設定すると、Claude Code はそれをサーバーの認証情報として使用し、そのサーバーでは OAuth にフォールバックしません。

​

カスタム認証に動的ヘッダーを使用する

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

• コマンドは文字列キーと値のペアの JSON オブジェクトを stdout に書き込む必要があります
• Claude Code はコマンドをシェルで実行し、10 秒後にそれを放棄します
• Claude Code はサーバーを設定した場所によってコマンドの作業ディレクトリを選択するため、スクリプトを絶対パスとして指定するか、PATH に配置してください
• 動的ヘッダーは同じ名前の静的 headers を上書きします

​

ヘルパーが実行される場所

​

ヘルパーが読み取ることができる変数

• 削除される：プロジェクト .mcp.json またはプラグイン内のサーバー、およびプロジェクトまたは --add-dir ディレクトリからのエージェントファイル内のインラインサーバー
• 削除されない：ユーザーまたはローカルスコープ、管理 MCP、claude.ai コネクタのサーバー、または SDK や --mcp-config から提供されるサーバー、および ~/.claude/agents/ からのエージェントファイル、管理設定からのエージェントファイル、または --agents で渡されたエージェントファイル内のインラインサーバー

​

headersHelper が実行される前にフォルダーを信頼する

• カウントされない信頼：親フォルダーの信頼、および claude -p または SDK セッションが設定ファイルのフックに対して取得する自動信頼
• フォルダーを信頼するまで：Claude Code は静的 headers のみでサーバーを接続します。claude -p または SDK セッションでは、さらにサーバーごとに 1 行の headersHelper not run を stderr に出力し、信頼を付与する方法を示します。
• ダイアログなしで信頼する：~/.claude.json で projects["<path>"].hasTrustDialogAccepted を true に設定してください。<path> は、プロジェクト許可ルールとワークスペース信頼で説明されている、Claude Code が信頼のキーとするフォルダーです。

​

ヘッダーを必要とするゲートウェイの背後にある MCP サーバーにサインインする

• 設定を編集できるサーバー：headers で設定するか、headersHelper から返してください
• 管理 MCP またはプラグインが提供するサーバー：管理者またはプラグインの作成者に、サーバーのエントリにヘッダーを追加するよう依頼してください

• 認可ページ：このページへのサインインはブラウザーで行いますが、ブラウザーは設定済みのヘッダーを送信しません。ブラウザーにページではなくゲートウェイのエラーが表示される場合は、ゲートウェイの運用者に、ヘッダーなしでページを通過させるよう依頼してください。
• 別のオリジンにある認可サーバー：そのサーバーの前にあるゲートウェイもヘッダーを必要とする場合、サインインはそこで失敗します。そのゲートウェイの運用者に、ヘッダーなしで OAuth リクエストを通過させるよう依頼してください。

​

JSON 設定から MCP サーバーを追加する

# 基本的な構文
claude mcp add-json <name> '<json>'

# 例：JSON 設定を使用して HTTP サーバーを追加する
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 例：JSON 設定を使用して stdio サーバーを追加する
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 例：事前設定された OAuth 認証情報を使用して HTTP サーバーを追加する
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

​

Claude Desktop から MCP サーバーをインポートする

# 基本的な構文 
claude mcp add-from-claude-desktop 

claude mcp list 

​

claude.ai から MCP サーバーを使用する

/mcp

• ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、または apiKeyHelper がアクティブ
• Amazon Bedrock や Google Cloud の Agent Platform などのサードパーティプロバイダーがアクティブ
• ANTHROPIC_PROFILE、フェデレーション変数、またはアクティブな Anthropic profile が認証情報を提供
• CLAUDE_CODE_OAUTH_TOKEN が claude setup-token からのトークンを保持している（モデルリクエストのみを実行できます）

1. /login を実行して再度サインインします。
2. /mcp から connector を再度接続します。

​

Connector が Claude Code に到達する方法

• Cloud sessions: セッションに到達する allowedMcpServers および deniedMcpServers エントリ（例えば server-managed settings を通じて）は、配信された connector もフィルタリングします。セッションのプロキシは各 connector の URL を書き直すため、connector 自体の URL 用に書かれた serverUrl パターンはそれと一致しません。自己ホスト環境で URL allowlist と共に配信された connector を許可するには、Connector traffic leaves your network の下にリストされている serverUrl エントリを追加します。セッションを実行するホスト（例えば self-hosted runner host）に managed-mcp.json が存在する場合、Claude Code は配信された connector をドロップします。allowAllClaudeAiMcps を設定するかどうかに関わらず。
• Desktop app local and SSH sessions: デスクトップアプリは connector を in-process type: "sdk" サーバーとして登録し、MCP 設定または managed-mcp.json は到達しません。ユーザーは claude.ai/customize/connectors で connector を切断することで、自分のセッションから connector を除外します。組織は connector の tools をブロックするか、Claude Code in the desktop app を完全にオフにします。

​

Connector tools の組織コントロール

• ツールが ask に設定されている場合: Claude Code は呼び出しのたびに、Your organization requires approval for this tool という理由とともにプロンプトを表示します。このプロンプトは、acceptEdits、auto、bypassPermissions の権限モードでも表示されます。ターミナルでは、このプロンプトに選択を記憶するオプションはありません。ツールに一致する許可ルールがあってもプロンプトはスキップされません。プロンプトを一切表示しない dontAsk モードでは、Claude Code は代わりに呼び出しを拒否します。
• Tool が blocked に設定されている場合: Claude Code は Claude がそれを見る前に tool をフィルタリングするため、tool リストに表示されません。Claude Code が connector 自体を取得するセッションでは、/mcp tool リストは依然として tool を表示し、disabled by your organization としてマークされます。

​

claude.ai connector を無効にする

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Claude Code を MCP サーバーとして使用する

# Claude を stdio MCP サーバーとして起動する
claude mcp serve

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

which claude

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

​

MCP クライアントとして��ックグラウンドコマンドの���力を読み取る

• その時点までの出力を読み取るには: クライアントからそのパスのファイルを開くか、パスを file_path としてサーバーの Read ツールに渡します
• コマンドの終了を判定するには: npm test; echo DONE のように、command の値に固定文字列を echo する処理を追加します。その文字列がファイルに現れた時点で、コマンドは終了しています。この文字列がない場合、終了を示すものは何もありません。Claude Code はファイルに最終行を追加せず、クライアントにも通知しないためです。
• 長い出力の末尾を読み取るには: file_path のみを指定した Read は最初のページを返すか、ファイルがサイズ制限を超える場合は失敗します。offset と limit も渡してください。この方法はファイルサイズに関係なく機能します。
  1. offset と limit の両方を 1 に設定して Read を呼び出し、結果から totalLines を取得します
  2. offset を totalLines から 9 を引いた値に、limit を 10 に設定して、再度 Read を呼び出します
  3. 2 回目の呼び出しで返される最後の 10 行の中から、echo した文字列を探します

​

MCP 出力制限と警告

• 出力警告閾値：Claude Code は、MCP ツール出力が 10,000 トークンを超える場合に警告を表示します
• 設定可能な制限：MAX_MCP_OUTPUT_TOKENS 環境変数を使用して、許可される最大 MCP 出力トークン数を調整できます
• デフォルト制限：デフォルトの最大値は 25,000 トークンです
• スコープ：環境変数は、独自の制限を宣言していないツールに適用されます。anthropic/maxResultSizeChars を設定するツールは、MAX_MCP_OUTPUT_TOKENS に設定されている値に関係なく、テキストコンテンツに対してその値を代わりに使用します。画像データを返すツールは、引き続き MAX_MCP_OUTPUT_TOKENS の対象となります
• 制限を超える場合：画像コンテンツのない成功した結果がトークン制限を超える場合、Claude Code はそれをファイルに保存し、会話内でファイルパスを名前とするメッセージに置き換えます。そのため、Claude はコンテンツが必要な場合にファイルを読み取ります。ファイルはセッションの tool-results ディレクトリ内の ~/.claude/projects/ に配置されます。
• HTTP および SSE サーバーからのレスポンスサイズ：HTTP または SSE サーバーからのレスポンスが 16 MiB を超えると、Claude Code はその読み取りを停止し、リクエストは失敗します。この制限は、展開後の 1 つの JSON レスポンスボディ、またはイベントストリームの 1 つのイベントに適用されます。サーバーを管理している場合は、結果をページ分割するなどして、レスポンスごとに返すデータを減らし、制限内に収めてください
• WebSocket サーバーからのメッセージサイズ：WebSocket サーバーが 16 MiB を超えるメッセージを 1 つ送信すると、Claude Code は接続を閉じ、そのサーバーで進行中の呼び出しは失敗します。サーバーを管理している場合は、メッセージごとに返すデータを減らし、制限内に収めてください

• テキスト結果の文字数制限：anthropic/maxResultSizeChars を宣言していないツールの場合、Claude Code は画像コンテンツのない成功した結果が 50,000 文字を超えると、トークン数に関係なくファイルに保存します。MAX_MCP_OUTPUT_TOKENS を設定しても、この閾値は変わりません
• エラー結果：ツールが isError: true とマークされた結果を返す場合、Claude は結果のテキストをツールのエラーメッセージとして受け取ります。約 11,000 文字を超えるエラーテキストは、最初の 5,000 文字と最後の 5,000 文字のみが保持され、その間に削除された文字数を示すマーカーが挿入されます

export MAX_MCP_OUTPUT_TOKENS=50000
claude

​

特定のツールの制限を引き上げる

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

​

ツール結果内の画像

​

ルートレベルのコンビネータを持つツール入力スキーマ

• allOf：すべてのブランチからのプロパティがマージされ、各ブランチの required リストは引き続き適用されます
• anyOf と oneOf：すべてのブランチからのプロパティがマージされ、各ブランチの required リストはスキーマによって強制されるのではなく、ツールの説明に記述されます

​

無効な入力スキーマを持つツール

• トップレベルのプロパティ名は 1 ～ 64 文字の長さで、ASCII 文字と数字、_、.、- のみを使用する必要があります
• スキーマは JSON Schema draft 2020-12 メタスキーマに対して有効である必要があります。Claude Code は $schema を宣言していないスキーマと draft 2020-12 を宣言しているスキーマにこのチェックを適用します。他の方言を宣言しているスキーマはこのチェックをスキップしますが、上記のプロパティ名チェックは引き続き適用されます

• Claude はツールを変更されないまま受け取り、サーバーのログにはそのツールについて input schema would be rejected by the Anthropic API が記録されます
• その後 API がスキーマを拒否した場合は、API が入力スキーマを拒否するツールを参照してください

​

API が入力スキーマを拒否するツール

• ツールを位置で示す 400 エラーでセッションが失敗する場合: Tool input schema is invalid の手順に従ってください
• サーバーを使用している場合: 何もする必要はありません。Claude は引き続きツールを呼び出せますが、そのパラメータは見えません
• サーバーを保守している場合: サーバー上でツールの入力スキーマを修正してください。ログの行は The API said: と、API がスキーマを拒否した理由で終わります。Claude はパラメータを見ずにツールを呼び出すため、サーバーが受け取る引数を検証してください

​

名前が 128 文字を超えるツール

​

特定のツールに対して承認を要求する

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

​

2 回呼び出しても安全なツールをマークする

• idempotentHint：ツールは何かを変更する可能性がありますが、同じ引数で再度呼び出しても安全です
• readOnlyHint：ツールは何も変更しません。Claude Code は、このツールの呼び出しを他の読み取り専用の呼び出しと並列で実行することもあります。

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

​

MCP エリシテーション要求に応答する

• フォームモード: Claude Code はサーバーで定義されたフォームフィールド（例えば、ユーザー名とパスワードプロンプト）を含むダイアログを表示します。フィールドに入力して送信します。
• URL モード: Claude Code はブラウザでリンクを開くかどうかを確認します。サーバーはこのモードを、ターミナルの外で完了するフロー（サインインなど）に使用します。

​

Claude Code が宣言するエリシテーションモード

• プロトコルリビジョン 2026-07-28 を使用する接続
• それ以前のプロトコルリビジョン（2025-11-25 以前）での、ユーザーの Claude Code MCP 設定にある stdio、sse、http、ws サーバーへの接続。Claude Code v2.1.287 以降が必要です

​

MCP リソースを使用する

​

MCP リソースを参照する

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Compare @postgres:schema://users with @docs:file://database/user-model

​

MCP ツール検索によるスケーリング

​

MCP サーバー作成者向けのツール検索

• ツールが扱うタスクのカテゴリ
• Claude がツールを検索すべきタイミング
• サーバーが提供する主な機能

• サーバーの指示、および事前に読み込まれるツールの説明: 4,096 文字
• Claude がツール検索を通じて読み込むツールの説明: 16,384 文字

​

説明の長さの上限を変更する

​

ツールを事前に読み込むか遅延させるかをマークする

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

​

ツール検索を設定する

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 以降: Anthropic API と同様に、ツール検索はデフォルトでオンです。
• それより前の Agent Platform モデル: これらのモデルのサービングスタックは必要なベータヘッダーを拒否するため、Claude Code はすべての MCP ツールを事前に読み込みます。ENABLE_TOOL_SEARCH=true でもこれを上書きすることはできません。

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

​

LLM ゲートウェイ経由のツール検索

​

ENABLE_TOOL_SEARCH=auto のしきい値を下回っても遅延されたままのツール

​

サーバーを遅延読み込みの対象外にする

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

​

サーバーのツールを遅延させる

​

MCP プロンプトをコマンドとして使用する

​

MCP プロンプトを実行する

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

​

管理対象 MCP 設定