Connect Claude Code to tools via MCP

原典: Connect Claude Code to tools via MCP ／日本語版

一行要約

MCP を繋ぐ判断基準は「別のツールからチャットにデータをコピーしている自分に気づいたとき」。運用の要点は 3つのスコープの優先順位と、tool search による context 節約が既定で効いていること。

要点

Connect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard.

issue トラッカーや監視ダッシュボードなど、別のツールからチャットへデータをコピーしている自分に気づいたら、サーバを繋げ。

4つのトランスポート

種別	コマンド	備考
HTTP（推奨）	`claude mcp add --transport http <name> <url>`	クラウドサービスで最も広くサポートされる。JSON では `streamable-http` が `http` の別名として使える
SSE（非推奨）	`claude mcp add --transport sse <name> <url>`	HTTP が使えるならそちらを使う
stdio（ローカルプロセス）	`claude mcp add [options] <name> -- <command> [args...]`	システムアクセスやカスタムスクリプト向け
WebSocket	`claude mcp add-json` のみ	サーバから能動的にイベントを push する場合に向く。OAuth も `--transport` フラグも非対応（ヘッダ認証のみ）

-- の重要性（stdio）:

For stdio servers, the -- (double dash) separates Claude’s own options, such as --transport, --env, and --scope, from the command and arguments that run the server. Everything after -- is passed to the server untouched.

stdio のサーバでは、--（ダッシュ2つ）が Claude 自身のオプションと、サーバを起動するコマンドおよび引数とを区切る。-- より後はすべて、手を加えずそのままサーバへ渡される。

-- がないと、サーバ側の --port などを Claude Code が自分のオプションとして解釈しようとする。

--env の直後にサーバ名を置かない。 CLI が名前を別の KEY=value ペアとして読んで拒否する。

JSON 設定の落とし穴: url があって type がないエントリは設定エラー（Claude Code は type なしを stdio サーバと読むため）。

stdio サーバに渡される環境

CLAUDE_PROJECT_DIR がプロジェクトルートとして設定される。hook が受け取るのと同じもの。セッション中に作業ディレクトリを足しても変わらない安定したルート
サーバ自身のファイルシステムアクセスを許可ディレクトリ群に限定したいなら、MCP の roots/list リクエストを実装する。Claude Code は起動ディレクトリ + --add-dir などで許可した全ディレクトリを返し、集合が変わると notifications/roots/list_changed を送る

3つのスコープと優先順位

スコープ	ロードされる範囲	チーム共有	保存先
Local（既定）	現在のプロジェクトのみ	不可	`~/.claude.json`
Project	現在のプロジェクトのみ	可（version control 経由）	プロジェクトルートの `.mcp.json`
User	全プロジェクト	不可	`~/.claude.json`

MCP の “local scope” は一般の local settings とは別物。 MCP の local スコープは ~/.claude.json（ホーム）に、一般の local settings は .claude/settings.local.json（プロジェクト）に保存される。

優先順位（同名なら1つだけ接続され、フィールドはスコープ間でマージされない）:

Local
Project
User
plugin 提供のサーバ
claude.ai コネクタ

3つのスコープは名前で重複判定するが、plugin とコネクタはエンドポイントで判定する。 URL は、スキームやホストの大文字小文字・スキームの既定ポート（https の :443 など）・末尾のスラッシュだけが違うなら同じエンドポイントとみなす。パス・クエリ文字列・userinfo・既定でないポートが違えば別のサーバ。

project スコープのセキュリティ: 対話セッションでは .mcp.json のサーバを使う前に承認を求める。claude mcp reset-project-choices で選択をリセットできる。ただし claude -p、Agent SDK、cloud セッションではプロンプトを出せないので、確認なしでロードされる。 bypassPermissions で始めたセッションで、ユーザー設定か managed settings に skipDangerousModePermissionPrompt が入っている場合も同じく確認が飛ぶ。 排除したいなら disabledMcpjsonServers に入れる。

組織で中央管理するなら、managed-mcp.json による固定のサーバ集合、managedMcpServers による全ユーザーへの配布、allowedMcpServers / deniedMcpServers による制限がある（別文書 managed-mcp）。

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

${VAR} / ${VAR:-default}
展開できる場所: command、args、env、url、headers
未設定でデフォルトもない場合、設定はロードされるが claude mcp list に警告が出て、${VAR} の文字列がそのまま使われる
例外: リモートサーバの url と headers では、資格情報らしき名前が警告なしに空になる（下の「資格情報の環境変数は空として読まれる」）。警告が出ていないことは展開された証拠にならない

tool search（既定で有効）

Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on your context window. Claude Code doesn’t impose a fixed per-server tool cap; the practical limit is your context window budget.

セッション開始時にロードされるのはツール名とサーバの instructions だけなので、MCP サーバを増やしても context window への影響は小さい。Claude Code はサーバごとのツール数に固定の上限を設けていない。実際上の制約は context window の予算である。

`ENABLE_TOOL_SEARCH`	挙動
（未設定）	全 MCP ツールを遅延ロード。一部の環境では upfront にフォールバック
`true`	全ツールを遅延（一部環境の例外あり）
`auto`	閾値モード — context window の 10% に収まるなら upfront、超える分は遅延
`auto:N`	閾値を N%（0-100）に変える
`false`	全ツールを upfront ロード

tool search が効かない環境: Azure ホストの Microsoft Foundry デプロイ（サーバ側が拒否する）、ANTHROPIC_BASE_URL が first-party でないホストを指す場合（プロキシが tool_reference ブロックを転送しないため）。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定すると ENABLE_TOOL_SEARCH でも上書きできない。

特定のサーバだけ遅延から外す: そのサーバの設定に alwaysLoad: true（全トランスポートで使える）。 ENABLE_TOOL_SEARCH の設定に関係なく、そのサーバの全ツールがセッション開始時に context へ載る。サーバ側から個別のツールを指定することもできる（_meta に "anthropic/alwaysLoad": true）。

Use this for a small number of tools that Claude needs on every turn, since each upfront tool consumes context that would otherwise be available for your conversation.

毎ターン必要な少数のツールにだけ使え。先読みされるツールは、本来なら会話に使えたはずの context を消費するからである。

副作用が1つある: alwaysLoad: true にすると、起動がそのサーバのツールを待つ （5秒の接続タイムアウトが上限）。最初のプロンプトを組み立てる時点で揃っている必要があるため。有効な cached エントリを持つリモートサーバは接続せずにキャッシュから供給するので起動を止めない。それ以外のサーバは既定でバックグラウンド接続する（MCP_CONNECTION_NONBLOCKING=0 で待たせられる）。

MCP サーバ作者向け:

the server instructions field becomes more useful with tool search enabled. Server instructions help Claude understand when to search for your tools, similar to how skills work.

tool search を有効にすると、server instructions のフィールドがより有用になる。server instructions は、skill の仕組みと同じように、いつあなたのツールを検索すべきかを Claude が理解する助けになる。

書くべきこと: ツールが扱うタスクのカテゴリ / いつ検索すべきか / 主要な機能。ツールの description と server instructions は、それぞれ既定で 2,048 文字で切られるので、重要な情報を先頭に置く（上限はセッションの全 MCP サーバに対して CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH で変えられる。v2.1.280 以降）。

2つのクライアントランタイム（v1 / v2）

Claude Code は MCP TypeScript SDK 1.x の v1 と、2.0 に載って MCP プロトコル改訂 を足した v2 のどちらかで繋ぐ。v2.1.232 以降は v2 を使い、起動時に選んで終了まで変えない。

v1 に落ちる条件: Amazon Bedrock / Claude Platform on AWS / Google Cloud Agent Platform / Microsoft Foundry（ホスト側が CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定している場合を除く）、 Claude apps gateway 経由のサインイン、feature flag の取得を切っている場合。

v2 で変わること: 新しい改訂に対応しているか HTTP とコネクタのサーバに聞く （stdio にも聞くのは MCP_PROTOCOL_NEGOTIATION=auto のとき。ただし feature flag を取得するセッションでは、v2.1.285 以降 Anthropic が順次 stdio にも既定で聞くようにしている —— stdio の channel サーバを古いハンドシェイクに留めたいなら legacy。これは全サーバを留める）/ list_changed を 開きっぱなしのストリームで受ける / 新しい改訂で繋いだ channel サーバは channel として登録しない （その改訂は channel メッセージを運べないため）。

自分で選ぶなら MCP_SDK_GENERATION を v1 / v2、聞くかどうかは MCP_PROTOCOL_NEGOTIATION を auto / legacy。既定が v1 の環境で v2 に固定しても「聞く」ようにはならないので、 auto も併せて設定する。

切断・再接続とタイムアウト（運用で効く）

自動再接続（HTTP / SSE のみ。stdio はローカルプロセスなので再接続しない）:

場面	挙動
セッション途中の切断	指数バックオフで最大5回（1秒から始めて倍々）。その間 `/mcp` では pending、5回失敗で failed
起動時の初回接続失敗	一時的なエラー（5xx、接続拒否、タイムアウト）で最大3回再試行。認証エラーと not-found は再試行しない
接続後の `tools/list` などの発見リクエスト	一時的なエラーで最大3回。認証エラー・4xx・リクエストタイムアウトは再試行しない

自分で再試行するなら /mcp reconnect all（失敗したか認証が要る全サーバ。対話ターミナルでは v2.1.284 以降）。

再開直後に、まだ接続中のサーバのツールを Claude が呼ぶことがある。 初回の接続試行中なら最大10秒待って走らせる。間に合わないか、すでに失敗後の再試行に入っていれば No such tool available で失敗する。

認証エラーを再試行しないことには例外がある —— Authorization の供給元が headersHelper だけなら再試行する（毎回ヘルパを走らせるので新しい資格情報を拾えるから。下の「認証」節）。

接続に失敗したサーバは Claude に伝えられる（ToolSearch が何も見つけなかったときの結果にも含まれる）ので、Claude が応答の中で接続失敗を報告できる。ただしこれは tool search が要る。 tool search が無い構成（カスタム ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false、非対応モデル）や Bedrock / Google Cloud Agent Platform / Microsoft Foundry では伝えられない。

3種類のタイムアウトが重なっている（ここが最も間違えやすい）:

種類	既定	設定
wall-clock（1呼び出しの上限）	`MCP_TOOL_TIMEOUT` 未設定なら約28時間	`.mcp.json` の `timeout`（ミリ秒）が優先。1000 未満は無視され `MCP_TOOL_TIMEOUT` に落ちる
per-request（各リクエストの最初の1バイトまで。HTTP / SSE / コネクタのみ）	60秒	`timeout` か `MCP_TOOL_TIMEOUT` を 60秒以上にすると上がる。それより短くしても縮まらない。stdio と WebSocket には無い
idle（無応答・無進捗で中断）	HTTP / SSE / WebSocket / コネクタ 5分、stdio 30分	`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`（ミリ秒、`0` で無効）

進捗通知は wall-clock を延ばさない。 また 1000 以上の timeout は idle の下限としても働く（その時間より早く idle 打ち切りしない）。

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

An MCP tool call in the main conversation that is still running after two minutes moves to a background task instead of blocking the session.

本体の会話でのツール呼び出しが2分を超えてまだ走っていると、セッションを塞ぐ代わりにバックグラウンドタスクへ移る。

Claude はすぐにタスク ID を受け取って作業を続け、決着したら task notification で結果が届く。タスクは /tasks に出て停止もできるが、セッションを抜けると残らない。バックグラウンドでも上の wall-clock と idle の上限は効き続ける。

閾値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS（0 で無効）。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 でも切れる（他のバックグラウンド機能ごと）。

バックグラウンド化されない呼び出し: subagent からの呼び出し（本体の会話のものだけが対象）/ IDE サーバへの呼び出し / 非対話モード（CLAUDE_AUTO_BACKGROUND_TASKS=1 を設定した場合を除く。一度きりの実行は結果が届く前に終わりうるため）/ elicitation のダイアログが開いている間 （サーバが遅いのではなく入力待ちなので、閉じるまで見送る）。

elicitation（サーバからの問い合わせ）

サーバが自力で得られない情報を求めると、設定不要で対話ダイアログが出る。 form モード（サーバが定義したフォーム項目）と URL モード（ブラウザでリンクを開くか尋ね、承諾すると開く。サインインのように端末の外で終わる流れに使われる）の2つ。ダイアログを出さずに自動応答したいなら Elicitation hook を使う。

出力サイズの制御

項目	値
警告のしきい値	10,000 トークンを超えると警告
既定の上限	25,000 トークン
変更方法	`MAX_MCP_OUTPUT_TOKENS` 環境変数

サーバ作者側からの上書き: tools/list の応答で _meta["anthropic/maxResultSizeChars"] を設定すると、そのツールのしきい値を上げられる（上限 500,000 文字）。これはテキストコンテンツについて MAX_MCP_OUTPUT_TOKENS と独立に効く。画像データを返すツールは依然としてトークン上限に従う。

アノテーションがないと、しきい値を超えた結果はディスクに退避され、会話にはファイル参照が入る（画像を含まない成功した結果に限る。画像を返す結果はトークン上限に従い、退避されない）。

トークン上限とは別に、文字数の上限がある。 anthropic/maxResultSizeChars を宣言しないツールでは、画像を含まない成功した結果が 50,000 文字を超えると、トークン数に関わらずファイルに退避される（MAX_MCP_OUTPUT_TOKENS を上げても変わらない）。エラー結果（isError: true）は約11,000文字を超えると先頭5,000と末尾5,000だけが残り、間に削った文字数の印が入る。バックグラウンドに移った呼び出しの結果はタスク通知で届く。

画像のツール結果（PNG / JPEG / GIF / WebP）は、Claude には会話中にインラインで見える（モデルの画像サイズ上限に合わせて縮小・圧縮されうる）。あわせて原本が ~/.claude/projects/ 配下のセッションの tool-results ディレクトリに保存され、Claude にパスが渡るので、Bash などで切り抜き・変換・再利用できる（v2.1.283 以降）。--no-session-persistence や CLAUDE_CODE_SKIP_PROMPT_HISTORY でセッションの保存を切っていると、ファイルは書かれずインラインの複製だけになる。

特定ツールに毎回承認を要求する

サーバ作者は tools/list で _meta["anthropic/requiresUserInteraction"] を true にできる。

Claude Code shows that tool’s permission prompt on every call, even in acceptEdits, auto, and bypassPermissions permission modes, and doesn’t offer a “don’t ask again” option for it. Allow rules that match the tool don’t skip the prompt either. In dontAsk mode, which never prompts, Claude Code denies the call instead.

Claude Code はそのツールの permission プロンプトを毎回表示する。acceptEdits、auto、bypassPermissions の各モードにおいてさえである。そのツールについては「次回から確認しない」という選択肢も出さない。そのツールに一致する allow ルールがあっても、プロンプトは省略されない。決してプロンプトを出さない dontAsk モードでは、代わりに呼び出しを拒否する。

プロンプトは人に届かなければならない。 非対話モードの --permission-prompt-tool が allow を返しても、deny に変換される（MCP tool requires user interaction; not supported via --permission-prompt-tool）。Agent SDK の canUseTool は受け取って承認できる —— SDK アプリは人に見せる前提だから。Remote Control のようなワンタップ承認も、このツールでは出さずに完全な permission プロンプトを見せる（v2.1.214 以降は、安全警告や always-allow を含むリモートで描けない権限要求全般で同じ扱い）。

claude.ai のコネクタ

claude.ai のアカウントでログインしていれば、claude.ai で追加したサーバ（コネクタ）が自動的に使える。ただし取り込まれるのは、有効な認証方式が claude.ai のサブスクリプションログインのときだけ。 以前に /login していても、次のどれかが効いていると読み込まれない。

ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / apiKeyHelper
Amazon Bedrock や Google Cloud Agent Platform などのサードパーティプロバイダ
ANTHROPIC_PROFILE やフェデレーションの変数
claude setup-token が作る CLAUDE_CODE_OAUTH_TOKEN（モデル呼び出ししかできない）

/mcp に出ないときは /status でどの認証方式が効いているかを見る。 組織が認証を管理しているコネクタは managed と表示される（接続のしかたや組織のツール制御は変わらない）。一度もサインインしていないコネクタは Show unused connectors の下に畳まれる。

組織によるコネクタ制御

設定	挙動
ツールが `ask`	毎回確認。`acceptEdits` / `auto` / `bypassPermissions` でも出る。記憶の選択肢もなく、allow rule でもスキップされない。`dontAsk` では拒否される
ツールが `blocked`	Claude が見る前にフィルタされる。Claude のツール一覧に現れない（Claude Code が自分でコネクタを取りに行くセッションでは、`/mcp` の一覧には `disabled by your organization` の印つきで出る）

認証（OAuth と独自ヘッダ）

リモートサーバが 401 / 403 を返すと「要認証」として /mcp に旗が立つ。 ただし旗が立たない場合が3つある。

場面	旗が立たない理由と代わりの表示
claude.ai コネクタが session token を拒否した `401`	コネクタを再認可してもログインは直らない。session-token-rejected として表示される。直すのは `/login` で入り直してから `/mcp` でコネクタを繋ぎ直すの順
`headers` か `headersHelper` で `Authorization` を自分で設定したサーバ	直すべき資格情報は自分が設定したほう。接続失敗として報告される（OAuth にフォールバックしない）
cloud セッションに配られたコネクタ	セッションのプロキシが claude.ai で与えた認可で認証するため、サインインの流れが無い。再認可は claude.ai 側で行う

サインイン済みのサーバが 401 を返したら、トークンを更新して再接続し、1回だけ再試行する。 それも失敗したときだけ旗が立つ
refresh token 自体が拒否されたら即座に通知が出る。 /mcp の Re-authenticate で入り直す
非対話モードでは OAuth の流れを回せない。 tool search が有効（既定）なら、「認可されるまでこのサーバのツールは使えない」ことが Claude に伝わるので、Claude はサーバ名を挙げて報告できる。サインインは対話セッションの /mcp か claude mcp login <name> で

MCP OAuth の資格情報は、HTTPS か localhost / 127.0.0.1 / ::1 の token endpoint にしか送らない。 それ以外の平文 http://（ローカルネットワークの機器など）ではサインインが失敗する。

OAuth の細かい制御（.mcp.json の oauth オブジェクト）:

フィールド	効果
`authServerMetadataUrl`	既定の discovery 連鎖を迂回して、指定した authorization server metadata URL を使う。既定は RFC 9728 の `/.well-known/oauth-protected-resource` → RFC 8414 の `/.well-known/oauth-authorization-server`
`oauth.scopes`	要求するスコープを固定する（空白区切りの1文字列）。セキュリティチームが承認した部分集合に絞る正式な方法。`authServerMetadataUrl` より優先される

未設定なら、サーバの WWW-Authenticate か protected resource metadata が示したスコープだけを要求し、どちらも無ければ scope を送らない（v2.1.196 以降）。例外は authServerMetadataUrl を設定した場合 —— そこから取った metadata の scopes_supported がそのまま要求スコープになる（上流が広告するスコープも上書きする）ので、内部プロキシを指すためだけに設定すると、カタログ全部を要求して下の invalid_scope を踏む。以前は discovery で見つけた scopes_supported の全部を要求していて、管理者専用スコープを広告する IdP が invalid_scope で拒否していた。oauth.scopes を固定したなら、後から必要になったスコープは自分で足さないと、認証し直しても付いてこない。

OAuth 以外の認証は headersHelper —— 接続時にコマンドを走らせ、その出力（JSON）を接続ヘッダにマージする。Kerberos・短命トークン・社内 SSO 向け。

ヘルパには CLAUDE_CODE_MCP_SERVER_NAME と CLAUDE_CODE_MCP_SERVER_URL が環境変数で渡る
headersHelper が Authorization の唯一の供給元なら、認証エラーでも再試行される（毎回ヘルパを走らせるので新しい資格情報を拾えるため）
plugin の headersHelper から ${user_config.*} は参照できない（シェル経由で走るため。設定ミスとして報告される）。headers 側に書くか、ヘルパが設定ファイルを読む
作業ディレクトリはそのサーバを宣言した設定ファイルで決まる。 Claude が Bash で cd しても動かない
自分が書いていないヘルパからは、資格情報らしき環境変数が取り除かれる。 名前に TOKEN / SECRET / PASSWORD / KEY / AUTH を含むもの（大文字小文字を問わない）と、ANTHROPIC_CUSTOM_HEADERS のような固定の一覧が対象。$MY_REGISTRY_TOKEN を読むヘルパは空のトークンを吐いて「接続失敗」になる
- 取り除かれる: プロジェクトの .mcp.json、plugin、プロジェクトや --add-dir 由来の agent ファイルのインラインサーバ
- 取り除かれない: user / local スコープ、managed MCP、claude.ai コネクタ、SDK や --mcp-config、~/.claude/agents/ や managed / --agents の agent ファイル
- 該当するなら、ヘルパはファイルか資格情報ストアから読む。 サーバの url にその変数の値が入っている場合、ヘルパが受け取る CLAUDE_CODE_MCP_SERVER_URL でもその部分が REDACTED になる

資格情報の環境変数は空として読まれる

リモートサーバの url と headers では、資格情報らしき環境変数は展開されず空になる。 プロジェクトの .mcp.json や plugin が、自分の Claude Code やクラウドの資格情報を勝手に外へ送れないようにするため。

対象は Claude Code 自身の資格情報（ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN など）、クラウドの資格情報（AWS_BEARER_TOKEN_BEDROCK など）、環境が持つその他（HTTPS_PROXY、NPM_TOKEN など）
設定してあってもいなくても空になり、:-default のフォールバックも無視される。警告も出ない
Bearer ${ANTHROPIC_AUTH_TOKEN} と書くと Bearer だけが飛び、たいてい 401 になって接続失敗として見える
ANTHROPIC_BASE_URL のような base URL は展開される（"url": "${ANTHROPIC_BASE_URL}/mcp" は動く）。ただし URL 自体に資格情報が埋まっていれば別
対象の集合の外の名前（API_KEY など）は書いたとおり展開される。 だから対象の資格情報を渡したいなら、自分の名前の変数に写してそちらを参照するのが正式な方法
踏んだときの唯一の手がかりは debug ログ。 claude --debug-file /tmp/claude-debug.log で走らせ、never expanded toward a remote server を探す

root レベルの combinator を持つスキーマ

一部の MCP サーバは入力スキーマのトップレベルに anyOf / oneOf / allOf を置く。Claude API はスキーマのルートでこれらを受け付けない。

v2.1.195 以降、Claude Code はスキーマを単一のオブジェクトに平坦化し、どのパラメータ群が組になるかを説明する文をツールの description に前置する。

allOf — 全ブランチのプロパティをマージし、各ブランチの required は依然として適用される
anyOf / oneOf — プロパティをマージし、各ブランチの required はスキーマではなく description で説明される（強制されない）

Your server receives whichever arguments Claude chose, so keep validating the combination server-side.

サーバは Claude が選んだ引数をそのまま受け取るので、その組み合わせの検証はサーバ側で続けよ。

resources と prompts

resources — @server:protocol://resource/path の形で @ メンションできる。自動的に取得され添付として含まれる
prompts — /mcp__servername__promptname の形でコマンドとして現れる。引数は空白区切りで渡す

そのまま使える具体例

サーバの追加:

# HTTP（推奨）
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
 
# stdio（-- の後はそのままサーバに渡る）
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
 
# WebSocket（add-json のみ）
claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
 
# スコープ指定
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

管理:

claude mcp list                      # 一覧
claude mcp get notion                # 詳細
claude mcp remove notion             # 削除
claude mcp reset-project-choices     # .mcp.json の承認をリセット
claude mcp serve                     # Claude Code 自身を stdio MCP サーバとして起動
/mcp                                 # セッション内で状態とトークンコストを確認

チーム共有用の .mcp.json（環境変数展開でシークレットを外に出す）:

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

tool search の調整:

ENABLE_TOOL_SEARCH=auto:5 claude    # 閾値 5%
ENABLE_TOOL_SEARCH=false claude     # 無効化
export MAX_MCP_OUTPUT_TOKENS=50000  # トークン上限を上げる（50,000 文字の退避しきい値は変わらない）

タイムアウトとバックグラウンド化:

export MCP_TIMEOUT=10000                          # サーバ起動のタイムアウト
export MCP_TOOL_TIMEOUT=600000                    # 1呼び出しの wall-clock
export CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0        # idle 打ち切りを無効化
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0       # 自動バックグラウンド化を切る
export MCP_SDK_GENERATION=v2                      # クライアントランタイムを固定
export MCP_PROTOCOL_NEGOTIATION=auto              # 新しい改訂を stdio にも聞く

サーバ単位の timeout と、遅延から外す指定:

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

ToolSearch ツール自体を封じる:

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

claude.ai コネクタを無効化する（any-source-true セマンティクス — どこかで true なら勝つ）:

{
  "disableClaudeAiConnectors": true
}

サーバ作者が大きな出力を許可する:

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

resource と prompt の呼び出し:

Can you analyze @github:issue://123 and suggest a fix?
Compare @postgres:schema://users with @docs:file://database/user-model
 
/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

原典で言及されている関連文書

code-execution-with-mcp — ツール定義と中間結果のトークン問題への根本的な対処
manage-tool-context — tool search / programmatic tool calling / caching / context editing の使い分け
features-overview — MCP と skill の使い分け（「MCP が接続、skill が使い方」）
permission-modes — コネクタツールの ask がどのモードでも効くこと
desktop-extensions — MCP サーバの梱包と配布
skills — server instructions が skill の description と同じ役割を持つこと
hooks — elicitation に自動応答する hook（原典が指すのは #elicitation の節）
env-vars — MCP_SDK_GENERATION などの環境変数
plugins — plugin 提供の MCP サーバ

ai-docs

エクスプローラー

Connect Claude Code to tools via MCP

一行要約

要点

4つのトランスポート

stdio サーバに渡される環境

3つのスコープと優先順位

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

tool search（既定で有効）

2つのクライアントランタイム（v1 / v2）

切断・再接続とタイムアウト（運用で効く）

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

elicitation（サーバからの問い合わせ）

出力サイズの制御

特定ツールに毎回承認を要求する

claude.ai のコネクタ

組織によるコネクタ制御

認証（OAuth と独自ヘッダ）

資格情報の環境変数は空として読まれる

root レベルの combinator を持つスキーマ

resources と prompts

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

ai-docs

エクスプローラー

Connect Claude Code to tools via MCP

一行要約

要点

4つのトランスポート

stdio サーバに渡される環境

3つのスコープと優先順位

.mcp.json の環境変数展開

tool search（既定で有効）

2つのクライアントランタイム（v1 / v2）

切断・再接続とタイムアウト（運用で効く）

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

elicitation（サーバからの問い合わせ）

出力サイズの制御

特定ツールに毎回承認を要求する

claude.ai のコネクタ

組織によるコネクタ制御

認証（OAuth と独自ヘッダ）

資格情報の環境変数は空として読まれる

root レベルの combinator を持つスキーマ

resources と prompts

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

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