MCPコネクタ

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



主な機能

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



ClaudeがMCPツールを使用するタイミング

MCPサーバーが接続されると、Claudeはユーザーのリクエストがツールの記述された機能に対応する場合にそのツールを呼び出します。これは明示的な場合（「Jiraで未解決のバグを検索して」）と暗黙的な場合（Jiraサーバーが接続された状態で「リリースを妨げているものは何？」）の両方があります。

Claudeは、接続されたサービスに関する一般的な知識の質問に対してはMCPツールを呼び出しません。Notionサーバーが接続された状態で「Notionデータベースはどのように機能しますか？」と尋ねた場合は直接回答されますが、「私のProjectsデータベースには何がありますか？」と尋ねた場合はツールがトリガーされます。

ClaudeがMCPツールをどの程度積極的に呼び出すかは、システムプロンプトを通じて調整できます。一般的なガイダンスと例文については、Claudeがツールを使用するタイミングを参照してください。



制限事項

• MCP仕様の機能セットのうち、現在サポートされているのはツール呼び出しのみです。
• サーバーはHTTP経由で公開されている必要があります（Streamable HTTPとSSEの両方のトランスポートをサポート）。ローカルのSTDIOサーバーに直接接続することはできません。



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

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

1. MCPサーバー定義（mcp_servers配列）：サーバー接続の詳細（URL、認証）を定義します
2. MCPツールセット（tools配列）：有効にするツールとその設定方法を構成します



基本的な例

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

client = anthropic.Anthropic()

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

print(response)



MCPサーバー設定

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

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



フィールドの説明



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



フィールドの説明



ツール設定オプション

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

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



設定のマージ

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

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

例：

{
  "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に複数のサーバー定義を含め、それぞれに対応するMCPToolsetをtools配列に含めることで、複数のMCPサーバーに接続できます。

{
  "model": "claude-opus-5",
  "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
      }
    }
  ]
}

多くのツールが利用可能な場合、Claudeはツール名と説明に基づいて選択します。明確で具体的なツールの説明により、選択の精度が向上します。大規模なツールセット（複数のサーバーにわたる数十のツール）の場合は、ツール検索ツールと併せてdefer_loadingを有効にし、クエリごとに関連するツールのみが表示されるようにすることを検討してください。



認証

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



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

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

1. 以下のコマンドでインスペクターを実行します。マシンにNode.jsがインストールされている必要があります。

   npx @modelcontextprotocol/inspector

   

2. 左側のサイドバーで、「Transport type」に「SSE」または「Streamable HTTP」のいずれかを選択します。

3. MCPサーバーのURLを入力します。

4. 右側のエリアで、「Need to configure authentication?」の後にある「Open Auth Settings」ボタンをクリックします。

5. 「Quick OAuth Flow」をクリックし、OAuth画面で認証します。

6. インスペクターの「OAuth Flow Progress」セクションの手順に従い、「Authentication complete」に到達するまで「Continue」をクリックします。

7. access_tokenの値をコピーします。

8. MCPサーバー設定のauthorization_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ヘルパー

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



インストール

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

pip install "anthropic[mcp]"



利用可能なヘルパー

お使いの言語のヘルパーをインポートします。

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

ヘルパー名と正確なシグネチャは各言語の規約に従います。この表はTypeScriptの形式を示しています。



MCPツールの使用

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

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # MCPサーバーに接続する
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # ツールを一覧取得してClaude API用に変換する
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())



MCPプロンプトの使用

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

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)



MCPリソースの使用

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

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# As a file upload
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)



エラー処理

変換関数は、MCP値がClaude APIでサポートされていない場合にUnsupportedMCPValueErrorをスローします（GoではヘルパーがUnsupportedValueErrorを返し、JavaとC#ではAnthropicInvalidDataExceptionをスローします）。これは、サポートされていないコンテンツタイプ、MIMEタイプ、またはリソースリンクで発生する可能性があります（変換前にMCPクライアントでリソースリンクを解決してください）。



バッチリクエスト

Message Batches APIリクエストにmcp_serversを含めることができます。Batches APIを通じたMCPツール呼び出しは、通常のMessages APIリクエストと同じ料金で課金されます。



データ保持

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

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



移行ガイド

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



主な変更点

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



移行手順

移行前（非推奨）：

{
  "model": "claude-opus-5",
  "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-5",
  "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
        }
      }
    }
  ]
}



一般的な移行パターン



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

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



非推奨フィールドの説明