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

フィールドの説明

mcp-client-2026-09-15ベータヘッダーを使用すると、MCPToolsetはサーバーのツールリストの固定されたコピーであるtoolsも受け入れます。MCPサーバーのツールリストを固定するを参照してください。

ツール設定オプション

各ツール（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サーバーはいつでもそのツールを変更できます。mcp-client-2026-09-15ベータヘッダーは、各サーバーが返すツールリストを記録し、そのリストを固定できるようにします。これにより、サーバーがツールを変更しても、会話の途中でClaudeから見えるツールが変わることはありません。このヘッダーにはmcp-client-2025-11-20の機能がすべて含まれているため、そのヘッダーの代わりに送信してください。Claude APIで利用できます。

レスポンスを生成する際にAPIがMCPサーバーにそのツールを要求すると、レスポンスはそのサーバーのmcp_tool_listingブロックで始まり、要求した各サーバーごとに1つのブロックが含まれます。

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

コードがcontent[0]を読み取る場合は、これらのブロックをスキップしてください。mcp_tool_listingブロックを含め、アシスタントメッセージを変更せずに返送し、このブロックを含むすべてのリクエストでmcp-client-2026-09-15を送信し続けてください。その後のリクエストでは、そのサーバーに再度要求する代わりに、記録されたリストを使用します。

リストを自分で固定するには、ブロックのtoolsをそのサーバーのMCPToolsetのtoolsフィールドにコピーします。こうすると、APIはサーバーにツールを要求せず、ツールセットのツールは、default_configとconfigsを適用したそれらのエントリだけになります。

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

tools内の各エントリは、サーバーがリストするツールのname（サーバー名なし）、そのdescription、およびそのinput_schemaを保持します。

次の例では、固定されていないツールセットで1つのリクエストを送信し、返されたリストをツールセットのtoolsフィールドにコピーして、リクエストを再度送信します。2番目のレスポンスにはmcp_tool_listingブロックがありません。APIがサーバーに要求しないためです。

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
# そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# リストを固定する: ブロックのツールをツールセットにコピーします。APIは
# これらのエントリを正確に使用し、サーバーに再度問い合わせません。
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
print([block.type for block in second.content])

inline-tools-2026-09-15ベータヘッダーも使用すると、会話の途中でMCPサーバーを追加できます。会話の途中でMCPサーバーを追加するを参照してください。

複数のMCPサーバー

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

{
  "model": "claude-opus-5-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ツールの使用

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

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

非推奨フィールドの説明

Compatibility