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… 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 とコネクタはエンドポイントで判定する。

project スコープのセキュリティ: 対話セッションでは .mcp.json のサーバを使う前に承認を求める。claude mcp reset-project-choices で選択をリセットできる。ただし claude -p、Agent SDK、cloud セッションではプロンプトを出せないので、確認なしでロードされる。 排除したいなら disabledMcpjsonServers に入れる。

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

${VAR} / ${VAR:-default}
展開できる場所: command、args、env、url、headers
未設定でデフォルトもない場合、設定はロードされるが claude mcp list に警告が出て、${VAR} の文字列がそのまま使われる

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 でも上書きできない。

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 はそれぞれ 2KB で切られるので、重要な情報を先頭に置く。

出力サイズの制御

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

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

アノテーションがないと、しきい値を超えた結果はディスクに退避され、会話にはファイル参照が入る。

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

サーバ作者は 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. Allow rules that match the tool don’t skip the prompt either. In dontAsk mode, Claude Code denies the call instead. Claude Code はそのツールの permission プロンプトを毎回表示する。acceptEdits、auto、bypassPermissions の各モードにおいてさえである。そして「次回から確認しない」という選択肢も出さない。そのツールに一致する allow ルールがあっても、プロンプトは省略されない。dontAsk モードでは、Claude Code は代わりに呼び出しを拒否する。

組織によるコネクタ制御

設定	挙動
ツールが `ask`	毎回確認。`acceptEdits` / `auto` / `bypassPermissions` でも出る。記憶の選択肢もなく、allow rule でもスキップされない。`dontAsk` では拒否される
ツールが `blocked`	Claude が見る前にフィルタされる。ツール一覧に現れない

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  # 出力上限を上げる

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 と同じ役割を持つこと

未取得の派生リンク

https://code.claude.com/docs/en/managed-mcp — 組織による一元管理（allowedMcpServers / deniedMcpServers）
https://code.claude.com/docs/en/mcp-quickstart — 最初の1台を繋ぐ手順
https://code.claude.com/docs/en/channels — MCP サーバから push されるメッセージ
https://code.claude.com/docs/en/plugins — plugin 提供の MCP サーバ

ai-docs

エクスプローラー

Connect Claude Code to tools via MCP

一行要約

要点

4つのトランスポート

stdio サーバに渡される環境

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

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

tool search（既定で有効）

出力サイズの制御

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

組織によるコネクタ制御

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

resources と prompts

そのまま使える具体例

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

未取得の派生リンク

グラフビュー

目次

バックリンク

ai-docs

エクスプローラー

Connect Claude Code to tools via MCP

一行要約

要点

4つのトランスポート

stdio サーバに渡される環境

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

.mcp.json の環境変数展開

tool search（既定で有効）

出力サイズの制御

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

組織によるコネクタ制御

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

resources と prompts

そのまま使える具体例

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

未取得の派生リンク

グラフビュー

目次

バックリンク

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