MCPとツールへの接続

上級

Model Context Protocol(MCP) はAIを外部ツールやデータに接続するためのオープン標準です。APIでは、自分でMCPクライアントを動かす必要は一切ありません:MCPコネクタを使えばリクエストの中にリモートサーバーの名前を書くだけで、Claudeが通常のエージェントループの中でそのツールを呼び出します。統合レイヤー全体を、2つのリクエストフィールドが置き換えます。

What you'll learn

MCPコネクタが自作ツール定義に勝つとき — そして勝たないとき
正確なリクエストの形:接続用のmcp_servers、ポリシー用のmcp_toolset
許可リスト、拒否リスト、ツールごとの設定 — そして3つの設定レイヤーがどうマージされるか
処理しなければならないレスポンスブロック:mcp_tool_useとmcp_tool_result
現実の制限:HTTPS限定、ツール限定、プラットフォームのギャップ、ZDR非対応

MCP対自作ツール

	ツール使用(カスタム)	MCPコネクタ
あなたが定義するもの	各ツールのスキーマ、そしてあなたが実行	ツールを公開するサーバーへの接続
ツールを実行するのは誰か	あなたのコード、あなたのループ内	Anthropic側がリモートサーバーを呼ぶ
最適な用途	アプリ内のいくつかの独自関数	既存の統合の再利用(GitHub、DB、ブラウザ、SaaS)
認証	あなたのコード	サーバーごとに供給するOAuthベアラートークン

両者は共存します。アプリ固有のツールは直接定義し、既製の能力はMCPで取り込んでください。

リクエストの形

2つの部品があり、意図的に別々になっています:**mcp_serversはサーバーがどこにあり、どう認証するかを述べ、tools配列内のmcp_toolset**エントリはどのツールを露出させ、どう扱うかを述べます。

Guided walkthrough1 of 4

anthropic-beta: mcp-client-2025-11-20 — これがないとmcp_serversフィールドは受け付けられません。SDKではbeta.messages.create呼び出しのbetasリストです。

最小限のMCPコネクタ呼び出し(cURL)

curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
  "model": "MODEL_ID",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "What tools do you have available?"}],
  "mcp_servers": [
    {"type": "url", "url": "https://example.com/sse", "name": "example-mcp", "authorization_token": "YOUR_TOKEN"}
  ],
  "tools": [
    {"type": "mcp_toolset", "mcp_server_name": "example-mcp"}
  ]
}'

:::tip モデルを決してハードコードしない上のMODEL_IDは意図的にプレースホルダです。現在のモデルと価格から現在のIDを読み、設定に保持してください、そうすればモデルのアップグレードが1行の変更になります。 :::

APIは厳格なペア規則を強制します:mcp_serversのすべてのサーバーはちょうど1つのtoolsetから参照されなければならず、すべてのtoolsetのmcp_server_nameは宣言されたサーバーと一致しなければなりません。不一致は無音のノーオペではなくバリデーションエラーです。

Claudeが実際にできることを選ぶ

これは多くの統合が誤る部分です。toolsetは、すべてのツールに適用されるdefault_configと、ツールごとの上書きのconfigsを取ります。優先順位、高い順に:ツールごとのconfigs → セットレベルのdefault_config → システムデフォルト。

拒否リスト — すべて有効にしてから危険なものを切る。広さは欲しいが破壊的な書き込みは要らないときに合理的:

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "configs": {
    "delete_all_events": { "enabled": false },
    "share_calendar_publicly": { "enabled": false }
  }
}

許可リスト — デフォルトで無効にし、生存者を名指す。これが最小権限の姿勢で、デフォルトで手を伸ばすべきもの:

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "default_config": { "enabled": false },
  "configs": {
    "search_events": { "enabled": true },
    "create_event": { "enabled": true }
  }
}

:::warning 拒否リストはあなたが思いついたものしかブロックしないサーバーはツールを追加できます。拒否リストは、あなたが書いた後に出荷されたすべてのツールを黙って許可します;許可リストはそれらを黙って無視します。顧客データや金銭に触れるものは、許可リストにしてください。また、サーバー上に存在しないツールをconfigsで指名するとバックエンド警告がログされますが、エラーにはなりません — なので許可リストのタイポは、有効にしたかったツールを黙って無効化します。サーバーのライブなツールリストで検証してください。 :::

スキーマをコンテキストから外す

有効なすべてのツールの説明はリクエストと共に送られるので、大きなカタログはすべてのターンに課税します。コネクタの答えはdefer_loading: true:説明は初期コンテキストから外され、Tool Search Toolを通じてClaudeが必要に応じて引き込みます。

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "default_config": { "defer_loading": true },
  "configs": {
    "search_events": { "defer_loading": false }
  }
}

これはこう読んでください:このタスクが始めに使う1つを除いてすべて遅延させる。toolsetはcache_controlも受け付けるので、安定したカタログを毎ターン再課金される代わりにプロンプトキャッシュのブレークポイントの背後に置けます。この背後の数字 — そしてなぜツールを遅延させることが選択精度を下げるどころか上げたのか — はMCPトークン税を参照。コンテキストを溢れさせているのが定義ではなく結果のときは、代わりにプログラマティックツール呼び出しに手を伸ばしてください。

返ってくるもの

処理しなければならない2つのコンテンツブロック型:

{ "type": "mcp_tool_use", "id": "mcptoolu_...", "name": "echo",
  "server_name": "example-mcp", "input": { "param1": "value1" } }

{ "type": "mcp_tool_result", "tool_use_id": "mcptoolu_...", "is_error": false,
  "content": [ { "type": "text", "text": "Hello" } ] }

useブロックのserver_nameに注目:複数のサーバーが接続されているとき、それが呼び出しの帰属先です — ログと、どの統合が誤動作したかのデバッグに不可欠。そしてis_errorはフィールドであって例外ではありません:失敗するMCPツールは結果として返ってくるので、ループはそれを検査しなければならず、成功を仮定してはいけません。

効いてくる制限

Watch out

ツールのみ。MCP仕様のうち、コネクタは現在ツール呼び出しをサポート — プロンプトやリソースはサポートしません。それらが必要?自分のクライアントを走らせ、代わりにSDK MCPヘルパーを使ってください。
リモートHTTPSのみ。サーバーはHTTP(Streamable HTTPまたはSSEトランスポート)で公にリーチ可能でなければなりません。ローカルstdioサーバーはこの方法では接続できません — それはClaude Codeとデスクトップアプリがすることです。
プラットフォームのギャップ。Claude API、AWS上のClaude Platform、Microsoft Foundry(Hosted-on-Anthropicデプロイメント)で利用可能。現在Amazon BedrockまたはGoogle Cloudではありません。
ゼロデータ保持なし。MCPサーバーと交換されるデータ — ツール定義と実行結果 — は標準保持に該当し、ZDRではありません。
OAuthはあなたが所有する。APIはauthorization_tokenを取ります;取得と期限前のリフレッシュはあなたの仕事です。

同じ標準、3つのサーフェス

API(このページ) — URLでリモートサーバーに、コネクタ経由。
Claude Code — 開発セッションでのローカルとリモートのサーバー。
アプリ — MCPがConnectorsを駆動。

プロトコルを一度学べば、それは転用できます。配線だけが異なります。

信頼

:::warning MCPサーバーはコードとアクセスの組み合わせ信頼できるサーバーだけ接続し、許可リストで最小権限にスコープし、サーバーが返す内容はプロンプトインジェクションを運びうる信頼できない入力であることを覚えておいてください。第三者のサーバーは配線前にレビュー — 第三者コードのレビューとMCPサーバーのセキュリティ確保。 :::

MCPコネクタ用語

Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。

1 / 6

理解度チェック

0/4

Claudeにカレンダーサーバーからsearch_eventsとcreate_eventだけを使わせたい。正しいtoolsetの形は?
MCPツール呼び出しが失敗しました。どこに現れますか?
ローカルstdioサーバーからMCPリソースをClaudeに読ませる必要があります。コネクタでできますか?
ツールカタログが4つのサーバーにまたがり、毎ターンコンテキストウィンドウを支配しています。最も安い最初の一手は?

Key takeaways

コネクタはMCPクライアントを2つのリクエストフィールドに置き換える — ただしリモートHTTPSサーバーに対し、ツール呼び出しのみ。
mcp_serversが接続、toolsのmcp_toolsetがポリシー。各サーバーはちょうど1つのtoolsetとペアにならなければならない。
許可リスト(default_config.enabled false、加えて明示的なconfigs)は拒否リストに勝つ:後からサーバーに追加されたツールは、許可されるのではなく無視される。
defer_loadingとcache_controlはツールスキーマがコンテキストウィンドウを食い始めたときのレバー。
mcp_tool_useとmcp_tool_resultブロックを処理する — 例外ではなくフィールドであるis_errorを含めて。
出荷前にベータヘッダを確認:mcp-client-2025-11-20が現在、mcp-client-2025-04-04は非推奨。

出典と参考文献

MCPコネクタ — Anthropicドキュメント — 権威あるフィールドリファレンスと移行ガイド。
Model Context Protocol仕様 — オープン標準そのもの、認可を含む。

MCP対自作ツール​

リクエストの形​

最小限のMCPコネクタ呼び出し(cURL)

Claudeが実際にできることを選ぶ​

スキーマをコンテキストから外す​

返ってくるもの​

効いてくる制限​

同じ標準、3つのサーフェス​

信頼​