MCPコネクタ

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

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

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

主な機能

直接API統合: MCPクライアントを実装せずにMCPサーバーに接続
ツール呼び出しサポート: Messages APIを通じてMCPツールにアクセス
柔軟なツール設定: すべてのツールの有効化、特定ツールの許可リスト、不要なツールの拒否リスト
ツールごとの設定: 個別のツールにカスタム設定を構成
OAuth認証: 認証が必要なサーバー向けのOAuth Bearerトークンのサポート
複数サーバー: 単一のリクエストで複数のMCPサーバーに接続

制限事項

MCP仕様の機能セットのうち、現在はツール呼び出しのみがサポートされています。
サーバーはHTTP経由で公開されている必要があります（Streamable HTTPと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`	string	はい	現在は"url"のみサポート
`url`	string	はい	MCPサーバーのURL。https://で始まる必要があります
`name`	string	はい	このMCPサーバーの一意の識別子。`tools`配列内のちょうど1つのMCPToolsetから参照される必要があります。
`authorization_token`	string	いいえ	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`	string	はい	"mcp_toolset"である必要があります
`mcp_server_name`	string	はい	`mcp_servers`配列で定義されたサーバー名と一致する必要があります
`default_config`	object	いいえ	このセット内のすべてのツールに適用されるデフォルト設定。`configs`内の個別のツール設定がこれらのデフォルトを上書きします。
`configs`	object	いいえ	ツールごとの設定オーバーライド。キーはツール名、値は設定オブジェクトです。
`cache_control`

ツール設定オプション

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

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

設定のマージ

設定値は以下の優先順位（高い順）でマージされます：

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-6",
  "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利用者は、API呼び出しを行う前にOAuthフローを処理してアクセストークンを取得し、必要に応じてトークンを更新することが期待されます。

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

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とAnthropic SDKを併用する際の手動変換コードが不要になります。

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

URL経由でアクセス可能なリモートサーバーがあり、ツールサポートのみが必要な場合は、mcp_servers APIパラメータを使用してください。Agent SDKを使用している場合、MCP接続は自動的に管理されます。ローカルサーバー、プロンプト、リソース、またはベース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ツールを`client.beta.messages.toolRunner()`で使用するためのClaude APIツールに変換します
`mcpMessages(messages)`	MCPプロンプトメッセージをClaude APIメッセージ形式に変換します
`mcpResourceToContent(resource)`	MCPリソースをClaude APIコンテンツブロックに変換します
`mcpResourceToFile(resource)`	MCPリソースをアップロード用のファイルオブジェクトに変換します

MCPツールの使用

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

import Anthropic from '@anthropic-ai/sdk';
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();

// MCPサーバーに接続
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);

// ツールをリストし、Claude API用に変換
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  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-5',
  max_tokens: 1024,
  messages: mcpMessages(messages),
});

MCPリソースの使用

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

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

// メッセージ内のコンテンツブロックとして
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: [
        mcpResourceToContent(resource),
        { type: 'text', text: 'Summarize this document' },
      ],
    },
  ],
});

// ファイルアップロードとして
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-client-2025-04-04ベータヘッダーを使用している場合は、このガイドに従って新しいバージョンに移行してください。

主な変更点

新しいベータヘッダー: mcp-client-2025-04-04からmcp-client-2025-11-20に変更
ツール設定の移動: ツール設定はMCPサーバー定義ではなく、tools配列内のMCPToolsetオブジェクトに配置されるようになりました
より柔軟な設定: 新しいパターンは許可リスト、拒否リスト、ツールごとの設定をサポートします

移行手順

変更前（非推奨）：

{
  "model": "claude-opus-4-6",
  "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-6",
  "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`	object	非推奨: 代わりに`tools`配列内のMCPToolsetを使用してください
`tool_configuration.enabled`	boolean	非推奨: MCPToolsetの`default_config.enabled`を使用してください
`tool_configuration.allowed_tools`	array	非推奨: MCPToolsetの`configs`で許可リストパターンを使用してください

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-4-6",
    "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"
      }
    ]
  }'