MCPコネクタでリモートMCPサーバーに接続する

Messages API に mcp_servers を渡すだけで、MCP クライアントを自前で実装せずにリモート MCP サーバーのツールを Claude に使わせられます。この記事では現行のベータヘッダー mcp-client-2025-11-20 を前提に、リクエストの書き方・ツールの絞り込み方・レスポンスの読み方を公式ドキュメントに沿って解説します。

MCPコネクタとは

MCP（Model Context Protocol）は、外部サービスの機能をツールとして共通の形で公開するための規格です。通常この規格を使うには、アプリケーション側に MCP クライアントを実装してサーバーと接続する必要があります。

MCP コネクタは、そのクライアント実装を Anthropic 側に肩代わりさせる機能です。Messages API のリクエストにサーバーの URL を書けば、API がサーバーへ接続し、ツール一覧を取得し、Claude が呼んだツールを実行して結果を返してくれます。アプリケーション側に増えるコードは、リクエストの JSON に数行足すだけです。

この機能を使うには、次のベータヘッダーが必要です。

anthropic-beta: mcp-client-2025-11-20

以前の mcp-client-2025-04-04 は非推奨になりました。旧版はツールの設定をサーバー定義の中（tool_configuration）に書く形式でしたが、現行版では後述するとおり tools 配列側の MCPToolset に移っています。

Claude がいつ MCP ツールを呼ぶかについては、公式に分かりやすい線引きがあります。接続したサービスに関する一般知識の質問（「Notion のデータベースはどういう仕組みですか」）には直接答え、そのサービス上の実データを必要とする質問（「私の Projects データベースには何が入っていますか」）でツールを呼びます。

リクエストの書き方

MCP コネクタは2つの部品でできています。接続先を定義する mcp_servers 配列と、どのツールを有効にするかを決める tools 配列の MCPToolset です。もっとも単純な、サーバーの全ツールを有効にする例が次のものです。

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": "claude-opus-5",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'

サーバー定義のフィールドは次のとおりです。

type（必須）… 現在は "url" のみ。
url（必須）… MCP サーバーの URL。https:// で始まる必要があります。
name（必須）… このサーバーを指す一意の識別子。ちょうど1つの MCPToolset から参照されなければなりません。
authorization_token（任意）… サーバーが OAuth 認証を要求する場合のアクセストークン。

ここで見落としやすいのが検証ルールです。mcp_servers に書いたサーバーは、必ずどれか1つの MCPToolset から参照されなければならず、逆に1つのサーバーを2つの MCPToolset から参照することもできません。サーバーだけ書いて tools を書き忘れると、リクエストは通りません。

認証が必要なサーバーの場合、OAuth フローを回してアクセストークンを取得するのはアプリケーション側の責任です。トークンの更新も同様です。テスト目的なら、MCP inspector（npx @modelcontextprotocol/inspector）の「Quick OAuth Flow」でトークンを取得し、その値を authorization_token に貼るのが手早い方法です。

ツールの許可リストと拒否リスト

MCPToolset は tools 配列に置き、default_config（そのサーバーの全ツールに適用する既定値）と configs（ツール名ごとの上書き）で構成します。

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

設定の優先順位は、configs のツール個別設定 > default_config > システム既定値の順です。この2段構えを理解すると、許可リストと拒否リストが同じ道具で書けることが分かります。

許可リスト（指定したツールだけ有効にする）は、既定を無効にしてから個別に有効化します。

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

拒否リスト（特定のツールだけ無効にする）は、既定のまま個別に無効化します。公式ドキュメントは、読み取り専用のアシスタントを作るときや、状態を変える操作の前に人間の確認を挟みたいときに、書き込み系・破壊的なツールを拒否リストに入れることを勧めています。

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

もう一つの設定値 defer_loading は、そのツールの説明文を最初からモデルに渡すかどうかを制御します（既定は false）。true にすると、ツール検索ツールで見つかったときだけ読み込まれます。ツールが数十個を超える構成では、この組み合わせでコンテキストの消費を大きく減らせます。

なお、configs に MCP サーバー側に存在しないツール名を書いてもエラーにはなりません（バックエンドに警告が記録されるだけです）。MCP サーバーは提供するツールを動的に変えられるためですが、裏を返せばツール名の打ち間違いに気づけないということでもあります。拒否リストを書いたつもりが1文字違いで機能していない、という事故が起きうるので、実際にツールが無効になっているかは応答で確認してください。

レスポンスに現れるブロック

Claude が MCP ツールを使うと、レスポンスの content に通常のツール使用とは別の2種類のブロックが現れます。

MCP ツール使用ブロックは、Claude がどのサーバーのどのツールを何の入力で呼んだかを示します。

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP ツール結果ブロックは、その実行結果です。

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

ここが通常のツール使用との決定的な違いです。ツールの実行は API 側で完結しているため、アプリケーションが tool_result を返す必要がありません。 自前でツールを定義する場合は「Claude がツールを呼ぶ → 自分で実行する → 結果を返す」というループを回しますが、MCP コネクタではそのループが不要です。is_error を見て失敗を検知する程度で済みます。

複数のサーバーに同時に接続することもできます。mcp_servers に複数のサーバー定義を並べ、それぞれに対応する MCPToolset を tools に置くだけです。ツールが増えるほど Claude はツール名と説明文から選ぶことになるので、説明文が具体的であるほど選択の精度が上がります。数十個を超える規模になったら、defer_loading とツール検索ツールの併用を検討してください。

制限事項と注意点

便利な機能ですが、制限は明確です。導入前に次の4点を確認してください。

対応しているのはツール呼び出しだけです。MCP 仕様にはリソースやプロンプトといった機能もありますが、MCP コネクタが扱うのは tool calls のみです。
サーバーは公開された HTTP で到達できる必要があります（Streamable HTTP と SSE の両方に対応）。手元で動かすローカルの STDIO サーバーは直接つなげません。
利用できる基盤が限られます。 Claude API、Claude Platform on AWS、Microsoft Foundry で使えますが、Amazon Bedrock と Google Cloud では現時点で利用できません。
ZDR（ゼロデータ保持）の対象外です。 MCP サーバーとやり取りするデータ（ツール定義や実行結果を含む）は、Anthropic の標準的なデータ保持ポリシーに従って保持されます。機微なデータを扱うサーバーを接続する場合は、この点を先に確認してください。

ローカルのサーバーを使いたい、あるいは MCP のプロンプトやリソースも扱いたい場合は、MCP コネクタではなくクライアント側のヘルパーを使う経路があります。各言語の SDK には MCP の型を Claude API の型へ変換する関数（TypeScript なら mcpTools / mcpMessages / mcpResourceToContent / mcpResourceToFile）が用意されており、自分で張った MCP クライアント接続とツール使用のツールランナーを組み合わせられます。

公式の使い分けの指針は明快です。URL で到達できるリモートサーバーで、ツールだけあればよいなら mcp_servers パラメータ。ローカルサーバー・プロンプト・リソースが必要、あるいは接続をより細かく制御したいならクライアント側ヘルパー、となります。

なお、mcp_servers は Message Batches API のリクエストにも含められます。バッチ経由の MCP ツール呼び出しの料金は、通常の Messages API と同じです。