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サーバーを直接接続することはできません。
• MCPコネクタは、Claude API、Claude Platform on AWS、およびMicrosoft Foundryで利用できます。Microsoft Foundryでは、MCPコネクタにはHosted on Anthropicデプロイメントが必要です。現在、Amazon BedrockおよびGoogle Cloudでは利用できません。



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 tool useブロック

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



MCP tool resultブロック

{
  "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-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仕様のAuthorizationセクションを参照してください。



クライアントサイドMCPヘルパー

独自のMCPクライアント接続を管理する場合（たとえば、ローカルのstdioサーバー、MCPプロンプト、またはMCPリソースを使用する場合）、SDKはMCP型とClaude API型の間で変換を行うヘルパー関数を提供します。これにより、Anthropic SDKとともに各言語用のMCP SDK（たとえば、TypeScript MCP 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,
)

# メッセージ内のコンテンツブロックとして
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)

# ファイルアップロードとして
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.beta.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"]
      }
    }
  ]
}



非推奨フィールドの説明