MCPコネクタ

MCPコネクタ - Claude API Docs

ClaudeのModel Context Protocol（MCP）コネクタ機能により、Messages APIから別のMCPクライアントを実装することなく、リモートMCPサーバーに直接接続できます。

現在のバージョン: この機能にはベータヘッダーが必要です: "anthropic-beta": "mcp-client-2025-11-20"

前のバージョン（mcp-client-2025-04-04）は非推奨です。以下の非推奨バージョンドキュメントを参照してください。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

主な機能

直接API統合: MCPクライアントを実装することなくMCPサーバーに接続
ツール呼び出しサポート: Messages APIを通じてMCPツールにアクセス
柔軟なツール設定: すべてのツールを有効にするか、特定のツールをホワイトリストに登録するか、不要なツールをブラックリストに登録するか選択可能
ツール単位の設定: カスタム設定で個別のツールを設定
OAuth認証: 認証されたサーバー向けのOAuth Bearerトークンサポート
複数サーバー: 単一のリクエストで複数のMCPサーバーに接続

制限事項

MCP仕様の機能セットのうち、ツール呼び出しのみが現在サポートされています。
サーバーはHTTPを通じて公開されている必要があります（StreamableHTTPおよびSSEトランスポートの両方をサポート）。ローカルSTDIOサーバーは直接接続できません。
MCPコネクタは現在、Amazon BedrockおよびGoogle Vertexではサポートされていません。

Messages APIでのMCPコネクタの使用

MCPコネクタは2つのコンポーネントを使用します:

MCPサーバー定義 (mcp_servers配列): サーバー接続の詳細（URL、認証）を定義
MCPツールセット (tools配列): 有効にするツールと設定方法を設定

基本的な例

この例では、デフォルト設定でMCPサーバーのすべてのツールを有効にします:

MCPサーバー設定

mcp_servers配列内の各MCPサーバーは接続の詳細を定義します:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

フィールドの説明

プロパティ	型	必須	説明
`type`	文字列	はい	現在は「url」のみがサポートされています
`url`	文字列	はい	MCPサーバーのURL。https://で始まる必要があります
`name`	文字列	はい	このMCPサーバーの一意の識別子。`tools`配列内のMCPToolsetによって正確に1回参照される必要があります。
`authorization_token`	文字列	いいえ	MCPサーバーで必要な場合のOAuth認可トークン。MCP仕様を参照してください。

MCPツールセット設定

MCPToolsetはtools配列内に存在し、MCPサーバーのどのツールが有効になるか、およびそれらがどのように設定されるかを設定します。

基本的な構造

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

フィールドの説明

プロパティ	型	必須	説明
`type`	文字列	はい	「mcp_toolset」である必要があります
`mcp_server_name`	文字列	はい	`mcp_servers`配列で定義されたサーバー名と一致する必要があります
`default_config`	オブジェクト	いいえ	このセット内のすべてのツールに適用されるデフォルト設定。`configs`内の個別のツール設定がこれらのデフォルトをオーバーライドします。
`configs`	オブジェクト	いいえ	ツール単位の設定オーバーライド。キーはツール名、値は設定オブジェクトです。
`cache_control`

ツール設定オプション

各ツール（default_configまたはconfigsで設定されているかどうかに関わらず）は以下のフィールドをサポートします:

プロパティ	型	デフォルト	説明
`enabled`	ブール値	`true`	このツールが有効かどうか
`defer_loading`	ブール値	`false`	trueの場合、ツールの説明は最初はモデルに送信されません。ツール検索ツールで使用されます。

Anthropic提供ツールの完全なディレクトリとdefer_loadingなどのオプションプロパティについては、ツールリファレンスを参照してください。大規模なツールセット全体での検索については、ツール検索ツールを参照してください。

設定のマージ

設定値は以下の優先度（高から低）でマージされます:

configs内のツール固有の設定
セットレベルのdefault_config
システムデフォルト

例:

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

結果:

search_events: enabled: false（configsから）、defer_loading: true（default_configから）
その他すべてのツール: enabled: true（システムデフォルト）、defer_loading: true（default_configから）

一般的な設定パターン

すべてのツールをデフォルト設定で有効にする

最もシンプルなパターン - サーバーからすべてのツールを有効にします:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

ホワイトリスト - 特定のツールのみを有効にする

デフォルトとしてenabled: falseを設定し、特定のツールを明示的に有効にします:

{
  "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
    }
  }
}

混合 - ツール単位の設定を伴うホワイトリスト

ホワイトリストと各ツールのカスタム設定を組み合わせます:

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

この例では:

search_eventsはdefer_loading: falseで有効になります
list_eventsはdefer_loading: trueで有効になります（default_configから継承）
その他すべてのツールは無効になります

検証ルール

APIは以下の検証ルールを適用します:

サーバーが存在する必要があります: MCPToolset内のmcp_server_nameはmcp_servers配列で定義されたサーバーと一致する必要があります
サーバーが使用される必要があります: mcp_serversで定義されたすべてのMCPサーバーは正確に1つのMCPToolsetによって参照される必要があります
サーバーごとに一意のツールセット: 各MCPサーバーは1つのMCPToolsetによってのみ参照できます
不明なツール名: configs内のツール名がMCPサーバーに存在しない場合、バックエンド警告がログに記録されますがエラーは返されません（MCPサーバーは動的なツール可用性を持つ可能性があります）

レスポンスコンテンツタイプ

ClaudeがMCPツールを使用する場合、レスポンスには2つの新しいコンテンツブロックタイプが含まれます:

MCPツール使用ブロック

{
  "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"
    }
  ]
}

複数のMCPサーバー

mcp_serversに複数のサーバー定義を含め、tools配列内の各サーバーに対応するMCPToolsetを含めることで、複数のMCPサーバーに接続できます:

{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

認証

OAuth認証が必要なMCPサーバーの場合、アクセストークンを取得する必要があります。MCPコネクタベータはMCPサーバー定義でauthorization_tokenパラメータを渡すことをサポートしています。 APIコンシューマーはOAuthフローを処理し、APIコールを行う前にアクセストークンを取得し、必要に応じてトークンをリフレッシュすることが期待されます。

テスト用のアクセストークンの取得

MCPインスペクタは、テスト目的でアクセストークンを取得するプロセスをガイドできます。

以下のコマンドでインスペクタを実行します。マシンにNode.jsがインストールされている必要があります。
```
npx @modelcontextprotocol/inspector
```
左側のサイドバーで、「Transport type」に対して「SSE」または「Streamable HTTP」を選択します。
MCPサーバーのURLを入力します。
右側の領域で、「Need to configure authentication?」の後の「Open Auth Settings」ボタンをクリックします。
「Quick OAuth Flow」をクリックし、OAuthスクリーンで認可します。
インスペクタの「OAuth Flow Progress」セクションのステップに従い、「Authentication complete」に到達するまで「Continue」をクリックします。
access_token値をコピーします。

アクセストークンの使用

上記のいずれかのOAuthフローを使用してアクセストークンを取得したら、MCPサーバー設定で使用できます:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

OAuthフローの詳細な説明については、MCP仕様の認可セクションを参照してください。

クライアント側MCPヘルパー（TypeScript）

独自のMCPクライアント接続を管理する場合（例えば、ローカルstdioサーバー、MCPプロンプト、またはMCPリソース）、TypeScript SDKはMCPタイプとClaude APIタイプ間の変換を行うヘルパー関数を提供します。これにより、MCP SDKをAnthropicSDKと一緒に使用する場合、手動変換コードが不要になります。

これらのヘルパーは現在、TypeScript SDKでのみ利用可能です。

URLを通じてアクセス可能なリモートサーバーがあり、ツールサポートのみが必要な場合はmcp_servers APIパラメータを使用してください。ローカルサーバー、プロンプト、リソース、またはベースSDKとの接続をより詳細に制御する必要がある場合は、クライアント側ヘルパーを使用してください。

インストール

Anthropic SDKとMCP SDKの両方をインストールします:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

利用可能なヘルパー

ベータネームスペースからヘルパーをインポートします:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

ヘルパー	説明
`mcpTools(tools, mcpClient)`	MCPツールをClaude APIツールに変換して`client.beta.messages.toolRunner()`で使用
`mcpMessages(messages)`	MCPプロンプトメッセージをClaude APIメッセージ形式に変換
`mcpResourceToContent(resource)`	MCPリソースをClaude APIコンテンツブロックに変換
`mcpResourceToFile(resource)`	MCPリソースをアップロード用のファイルオブジェクトに変換

MCPツールを使用する

SDK のツールランナーで使用するためにMCPツールを変換します。これはツール実行を自動的に処理します:

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

MCPプロンプトを使用する

MCPプロンプトメッセージをClaude APIメッセージ形式に変換します:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

MCPリソースを使用する

MCPリソースをコンテンツブロックに変換してメッセージに含めるか、アップロード用のファイルオブジェクトに変換します:

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

エラーハンドリング

変換関数は、MCPの値がClaude APIでサポートされていない場合、UnsupportedMCPValueErrorをスローします。これは、サポートされていないコンテンツタイプ、MIMEタイプ、または非HTTPリソースリンクで発生する可能性があります。

データ保持

MCPコネクタはZDR契約の対象ではありません。MCPサーバーと交換されるデータ（ツール定義と実行結果を含む）は、Anthropicの標準データ保持ポリシーに従って保持されます。

すべての機能にわたるZDR適格性については、API とデータ保持を参照してください。

マイグレーションガイド

非推奨のmcp-client-2025-04-04ベータヘッダーを使用している場合は、このガイドに従って新しいバージョンにマイグレーションしてください。

主な変更点

新しいベータヘッダー: mcp-client-2025-04-04からmcp-client-2025-11-20に変更
ツール設定の移動: ツール設定はMCPサーバー定義ではなく、tools配列内のMCPToolsetオブジェクトに存在するようになりました
より柔軟な設定: 新しいパターンはホワイトリスト、ブラックリスト、およびツール単位の設定をサポートします

マイグレーションステップ

前（非推奨）:

{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

後（現在）:

{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

一般的なマイグレーションパターン

古いパターン	新しいパターン
`tool_configuration`なし（すべてのツールが有効）	`default_config`または`configs`なしのMCPToolset
`tool_configuration.enabled: false`	`default_config.enabled: false`を持つMCPToolset
`tool_configuration.allowed_tools: [...]`	`default_config.enabled: false`と`configs`で特定のツールが有効なMCPToolset

非推奨バージョン: mcp-client-2025-04-04

このバージョンは非推奨です。上記のマイグレーションガイドを使用してmcp-client-2025-11-20にマイグレーションしてください。

MCPコネクタの前のバージョンはMCPサーバー定義にツール設定を直接含めていました:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

非推奨フィールドの説明

プロパティ	型	説明
`tool_configuration`	オブジェクト	非推奨: 代わりに`tools`配列内のMCPToolsetを使用してください
`tool_configuration.enabled`	ブール値	非推奨: MCPToolset内の`default_config.enabled`を使用してください
`tool_configuration.allowed_tools`	配列	非推奨: MCPToolset内の`configs`を使用したホワイトリストパターンを使用してください

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)