---
title: MCPコネクタ
url: https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector
description: MCPクライアントなしでMessages APIから直接リモートMCPサーバーに接続し、個々のツールを許可リスト化、拒否リスト化、または設定します。
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
ClaudeのModel Context Protocol（MCP）コネクタ機能により、別個のMCPクライアントなしでMessages APIから直接リモートMCPサーバーに接続できます。
この機能の以前のバージョン（`mcp-client-2025-04-04`）は非推奨です。[非推奨バージョン: mcp-client-2025-04-04](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04)を参照してください。
## 主な機能
* **直接API統合:** MCPクライアントを実装せずにMCPサーバーに接続
* **ツール呼び出しサポート:** Messages APIを通じてMCPツールにアクセス
* **柔軟なツール設定:** すべてのツールを有効化、特定のツールを許可リスト化、または不要なツールを拒否リスト化
* **ツールごとの設定:** カスタム設定で個々のツールを設定
* **OAuth認証:** 認証されたサーバー向けのOAuth Bearerトークンをサポート
* **複数サーバー:** 単一のリクエストで複数のMCPサーバーに接続
## ClaudeがMCPツールを使用するタイミング
MCPサーバーが接続されると、ユーザーのリクエストがツールの記述された機能にマッピングされる場合、Claudeはそのツールを呼び出します。これは明示的（「Jiraでオープンなバグを検索して」）または暗黙的（Jiraサーバーが接続された状態で「リリースを妨げているものは何ですか？」）のいずれかです。
Claudeは、接続されたサービスに関する一般的な知識の質問に対してはMCPツールを呼び出し**ません**。Notionサーバーが接続された状態で「Notionデータベースはどのように機能しますか？」と尋ねると直接回答されますが、「私のProjectsデータベースには何がありますか？」と尋ねるとツールがトリガーされます。
システムプロンプトを通じて、ClaudeがどれだけすぐにMCPツールを呼び出すかを調整できます。一般的なガイダンスと例文については、[Claudeがツールを使用するタイミング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/overview#when-claude-uses-tools)を参照してください。
## 制限事項
* [MCP仕様](https://modelcontextprotocol.io/introduction#explore-mcp)の機能セットのうち、現在サポートされているのは[ツール呼び出し](https://modelcontextprotocol.io/docs/concepts/tools)のみです。
* サーバーはHTTPを通じて公開されている必要があります（Streamable HTTPとSSEの両方のトランスポートをサポート）。ローカルのSTDIOサーバーは直接接続できません。
## Messages APIでのMCPコネクタの使用
MCPコネクタは2つのコンポーネントを使用します。
1. **MCPサーバー定義**（`mcp_servers`配列）: サーバー接続の詳細（URL、認証）を定義
2. **MCPツールセット**（`tools`配列）: どのツールを有効にするか、およびそれらをどのように設定するかを構成
### 基本的な例
この例では、デフォルト設定でMCPサーバーのすべてのツールを有効にします。
```bash cURL
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-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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
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
YAML
```
```python Python
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)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.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"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1000,
Messages = new List
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5-5',
mcpServers: [
[
'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'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
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"]
)
puts response
```
## MCPサーバー設定
`mcp_servers`配列内の各MCPサーバーは接続の詳細を定義します。
```json
{
"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認証トークン。取得方法については[認証](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#authentication)を、プロトコルの詳細については[MCP仕様](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)を参照してください。 |
## MCPツールセット設定
MCPToolsetは`tools`配列内に存在し、MCPサーバーのどのツールが有効になっているか、およびそれらをどのように設定すべきかを構成します。
### 基本構造
```json
{
"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` | object | いいえ | このツールセットの[プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)キャッシュブレークポイント設定。 |
`mcp-client-2026-09-15`ベータヘッダーを使用すると、MCPToolsetはサーバーのツールリストの固定されたコピーである`tools`も受け入れます。[MCPサーバーのツールリストを固定する](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#pin-mcp-tool-list)を参照してください。
### ツール設定オプション
各ツール（`default_config`または`configs`で設定されているかどうかにかかわらず）は、以下のフィールドをサポートします。
| プロパティ | 型 | デフォルト | 説明 |
| --------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | このツールが有効かどうか。 |
| `defer_loading` | boolean | `false` | trueの場合、ツールの説明は最初はモデルに送信されません。[ツール検索ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool)と併用されます。 |
Anthropicが提供するツールの完全なディレクトリと`defer_loading`などのオプションプロパティについては、[ツールリファレンス](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference)を参照してください。大規模なツールセット全体を検索するには、[ツール検索ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool)を参照してください。
### 設定のマージ
設定値は、この優先順位（高いものから低いものへ）でマージされます。
1. `configs`内のツール固有の設定
2. セットレベルの`default_config`
3. システムデフォルト
例:
```json
{
"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から）
## 一般的な設定パターン
### デフォルト設定ですべてのツールを有効化
最もシンプルなパターン: サーバーのすべてのツールを有効にします。
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### 許可リスト: 特定のツールのみを有効化
デフォルトとして`enabled: false`を設定し、特定のツールを明示的に有効にします。
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### 拒否リスト: 特定のツールを無効化
デフォルトですべてのツールを有効にし、不要なツールを明示的に無効にします。読み取り専用アシスタントを構築する場合、または状態変更の前に人間による確認ステップを設けたい場合は、書き込みツールや破壊的なツールを拒否リスト化することをお勧めします。
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### 混合: ツールごとの設定を伴う許可リスト
許可リスト化と各ツールのカスタム設定を組み合わせます。
```json
{
"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ツール使用ブロック
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCPツール結果ブロック
```json
{
"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つのブロックが含まれます。
```json
{
"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`を適用したそれらのエントリだけになります。
```json
{
"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がサーバーに要求しないためです。
```bash cURL
BODY='{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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"
}
],
"messages": [
{
"role": "user",
"content": "What tools do you have available?"
}
]
}'
# 最初のリクエスト：ツールセットが固定されていないため、APIはサーバーに
# そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
# teeは変数がレスポンスをキャプチャする間、それをstderrに表示します。
FIRST=$(curl -sS 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-2026-09-15" \
-d "$BODY" | tee /dev/stderr)
# リストを固定：ブロックのツールをツールセットにコピーします。APIは
# これらのエントリを正確に使用し、サーバーに再度問い合わせません。
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
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-2026-09-15" \
-d "$PINNED"
```
```bash CLI
request=$(cat <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
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
messages:
- role: user
content: What tools do you have available?
YAML
)
# 最初のリクエスト：ツールセットがピン留めされていないため、APIはサーバーに
# そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
# teeは変数がレスポンスをキャプチャする間、それをstderrに表示します。
first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
<<<"$request" | tee /dev/stderr)
tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$first")
# リストをピン留め：ブロックのツールをツールセットにコピーします。--toolフラグは
# ボディのツール配列を置き換えます。APIはこれらのエントリを正確に使用し、
# サーバーに再度問い合わせないため、レスポンスにmcp_tool_listingブロックはありません。
ant beta:messages create --beta mcp-client-2026-09-15 \
--tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
<<<"$request"
```
```python Python
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])
```
```typescript TypeScript
const client = new Anthropic();
const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
];
const messages: Anthropic.Beta.BetaMessageParam[] = [
{ role: "user", content: "What tools do you have available?" }
];
// 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
// そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
const first = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages
});
const listing = first.content.find((block) => block.type === "mcp_tool_listing");
if (!listing) {
throw new Error("The response has no mcp_tool_listing block.");
}
console.log(listing.tools.map((tool) => tool.name));
// リストを固定する: ブロックのツールをツールセットにコピーします。APIは
// これらのエントリを正確に使用し、サーバーに再度問い合わせません。
const second = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools
}
],
messages
});
// 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックがありません。
console.log(second.content.map((block) => block.type));
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
AnthropicClient client = new();
List mcpServers =
[
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN",
},
];
List messages =
[
new() { Role = Role.User, Content = "What tools do you have available?" },
];
// 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
// そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
var first = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools = [new BetaMcpToolset("example-mcp")],
Messages = messages,
});
var listing = first.Content
.Select(block => block.Value)
.OfType()
.First();
Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));
// リストを固定する: ブロックのツールをツールセットにコピーします。APIは
// これらのエントリを正確に使用し、サーバーに再度問い合わせません。
var second = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools =
[
new BetaMcpToolset("example-mcp")
{
Tools =
[
.. listing.Tools.Select(tool => new BetaMcpToolParam
{
Name = tool.Name,
Description = tool.Description,
InputSchema = tool.InputSchema,
}),
],
},
],
Messages = messages,
});
// 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
```
```go Go
client := anthropic.NewClient()
mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
}
// 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
// そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
first, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
var listing anthropic.BetaMCPToolListingBlock
for _, block := range first.Content {
if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
listing = listingBlock
break
}
}
// リストを固定する: ブロックのツールをツールセットにコピーします。APIは
// これらのエントリを正確に使用し、サーバーに再度問い合わせません。
var toolNames []string
var pinnedTools []anthropic.BetaMCPToolParam
for _, tool := range listing.Tools {
toolNames = append(toolNames, tool.Name)
pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
Name: tool.Name,
Description: anthropic.String(tool.Description),
InputSchema: tool.InputSchema,
})
}
fmt.Println(toolNames)
second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
Tools: pinnedTools,
}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
var blockTypes []string
for _, block := range second.Content {
blockTypes = append(blockTypes, block.Type)
}
fmt.Println(blockTypes)
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMcpTool;
import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build();
// 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
// そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addUserMessage("What tools do you have available?")
.build());
BetaMcpToolListingBlock listing = first.content().stream()
.flatMap(block -> block.mcpToolListing().stream())
.findFirst()
.orElseThrow();
IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());
// リストを固定する: ブロックのツールをツールセットにコピーします。APIは
// これらのエントリを正確に使用し、サーバーに再度問い合わせません。
BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
.build())
.addUserMessage("What tools do you have available?")
.build());
// 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
IO.println(second.content().stream()
.map(block -> block.type().asString())
.toList());
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMCPTool;
use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
// ...
$client = new Client();
$mcpServers = [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
];
$messages = [['role' => 'user', 'content' => 'What tools do you have available?']];
// 最初のリクエスト: ツールセットが固定されていないため、APIはサーバーに
// そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
$first = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
messages: $messages,
);
$listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;
// リストを固定する: ブロックのツールをツールセットにコピーします。APIは
// これらのエントリを正確に使用し、サーバーに再度問い合わせません。
$second = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
'tools' => array_map(
fn (BetaMCPTool $tool) => [
'name' => $tool->name,
'description' => $tool->description,
'input_schema' => $tool->inputSchema,
],
$listing->tools,
),
],
],
messages: $messages,
);
// 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
mcp_servers = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
]
messages = [{ role: "user", content: "What tools do you have available?" }]
# 最初のリクエスト：ツールセットが固定されていないため、APIはサーバーに
# そのツールを問い合わせ、レスポンスはmcp_tool_listingブロックで始まります。
first = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages:
)
listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
puts listing.tools.map(&:name).inspect
# リストを固定：ブロックのツールをツールセットにコピーします。APIは
# これらのエントリを正確に使用し、サーバーに再度問い合わせません。
second = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools.map(&:to_h)
}
],
messages:
)
# 固定されたツールセットでは、レスポンスにmcp_tool_listingブロックはありません。
puts second.content.map(&:type).inspect
```
`inline-tools-2026-09-15`ベータヘッダーも使用すると、会話の途中でMCPサーバーを追加できます。[会話の途中でMCPサーバーを追加する](https://platform.claude.com/docs/ja/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta)を参照してください。
## 複数のMCPサーバー
`mcp_servers`に複数のサーバー定義を含め、`tools`配列にそれぞれ対応するMCPToolsetを含めることで、複数のMCPサーバーに接続できます。
```json
{
"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はツール名と説明に基づいて選択します。明確で具体的なツールの説明は選択の精度を向上させます。大規模なツールセット（複数のサーバーにまたがる数十のツール）の場合は、[ツール検索ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool)とともに[`defer_loading`](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#tool-configuration-options)を有効にして、クエリごとに関連するツールのみが表示されるようにすることを検討してください。
## 認証
OAuth認証を必要とするMCPサーバーの場合、アクセストークンを取得する必要があります。MCPコネクタベータは、MCPサーバー定義で`authorization_token`パラメータを渡すことをサポートしています。 APIコンシューマーは、API呼び出しを行う前にOAuthフローを処理してアクセストークンを取得し、必要に応じてトークンを更新することが期待されます。
### テスト用のアクセストークンの取得
MCPインスペクターは、テスト目的でアクセストークンを取得するプロセスをガイドできます。
1. 以下のコマンドでインスペクターを実行します。マシンにNode.jsがインストールされている必要があります。
```bash
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サーバー設定で使用できます。
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
OAuthフローの詳細な説明については、MCP仕様の[認可セクション](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)を参照してください。
## クライアントサイドのMCPヘルパー
独自のMCPクライアント接続を管理する場合（たとえば、ローカルのstdioサーバー、MCPプロンプト、またはMCPリソースを使用する場合）、SDKはMCPの型とClaude APIの型の間で変換を行うヘルパー関数を提供します。これにより、Anthropic SDKと併せてお使いの言語向けのMCP SDK（たとえば[TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)）を使用する際に、手動の変換コードが不要になります。
URLでアクセス可能なリモートサーバーがあり、ツールのサポートのみが必要な場合は、[`mcp_servers` APIパラメータ](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api)を使用してください。ローカルサーバー、プロンプト、リソースが必要な場合や、ベースSDKで接続をより細かく制御したい場合は、クライアントサイドのヘルパーを使用してください。
### インストール
Anthropic SDKとMCP SDKの両方をインストールします。
MCPヘルパーは`mcp`エクストラに含まれており、Python 3.10以降が必要です。
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
ヘルパーは別の`Anthropic.Mcp`パッケージに含まれています。MCPクライアント自体は公式の[ModelContextProtocolパッケージ](https://www.nuget.org/packages/ModelContextProtocol)から提供されます。
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
ヘルパーはGo SDKの`mcp`サブパッケージに含まれており、[MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)の上に構築されています。
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
ヘルパーは別の`anthropic-java-mcp`アーティファクトに含まれており、Java 17以降が必要です（ベースSDKはJava 8をサポートしています）。ベースの`anthropic-java`依存関係と併せて追加してください。
```kotlin
implementation("com.anthropic:anthropic-java:2.73.0")
implementation("com.anthropic:anthropic-java-mcp:2.73.0")
```
```xml
com.anthropic
anthropic-java
2.73.0
com.anthropic
anthropic-java-mcp
2.73.0
```
ヘルパーは公式の[MCP PHP SDK](https://packagist.org/packages/mcp/sdk)を使用します。
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
ヘルパーは公式の[`mcp` gem](https://rubygems.org/gems/mcp)を使用します。
```bash
bundle add anthropic mcp
```
### 利用可能なヘルパー
お使いの言語のヘルパーをインポートします。
```python Python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
```typescript TypeScript
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
```
```go Go
import (
"github.com/anthropics/anthropic-sdk-go/mcp"
)
```
```java Java
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
```
```ruby Ruby
require "anthropic"
# ヘルパーは Anthropic::Mcp モジュール上で公開されます
```
| ヘルパー | 説明 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`) | MCPツールを、`client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`)で使用するためのClaude APIツールに変換します |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`) | MCPプロンプトメッセージをClaude APIのメッセージ形式に変換します |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | MCPリソースをClaude APIのコンテンツブロックに変換します |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`) | MCPリソースをアップロード用のファイルオブジェクトに変換します |
### MCPツールの使用
ツールの実行を自動的に処理するSDKの[ツールランナー](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-runner)で使用するためにMCPツールを変換します。
```python Python
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())
```
```typescript TypeScript
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} 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();
// MCP SDK の callTool の戻り値型には、mcpTools が受け付けないレガシーな
// 結果形状がまだ含まれているため、型を絞り込みます。MCPClientLike が拡張されたら削除してください。
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClientForTools)
});
console.log(finalMessage);
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
using Anthropic.Models.Beta.Messages;
using ModelContextProtocol.Client;
using Messages = Anthropic.Models.Messages;
var anthropic = new AnthropicClient();
// MCPサーバーに接続する
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// ツールを一覧取得してClaude API用に変換する
var tools = await BetaMcp.ListToolsAsync(mcpClient);
var runner = anthropic.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "What tools do you have available?",
},
],
},
tools
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
import (
// ...
// ...
"github.com/anthropics/anthropic-sdk-go/mcp"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// MCPサーバーに接続する
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// ツールを一覧取得してClaude API用に変換する
toolsResult, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatal(err)
}
betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
if err != nil {
log.Fatal(err)
}
runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
},
})
finalMessage, err := runner.RunToCompletion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalMessage.RawJSON())
}
```
```java Java
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema;
// ...
void main() throws Exception {
AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();
// MCPサーバーに接続する
StdioClientTransport transport = new StdioClientTransport(
ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());
try (McpSyncClient mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
.build()) {
mcpClient.initialize();
// ツールを一覧取得し、Claude API 用に変換する
List betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What tools do you have available?")
.addTools(betaTools)
.build();
// ランナーはアシスタントのターンごとに1つのメッセージを生成し、最後のものが最終レスポンスです
BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
IO.println(finalMessage);
}
}
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
use Mcp\Client;
use Mcp\Client\Transport\HttpTransport;
$anthropic = new Anthropic();
// MCP サーバーに接続します。PHP の MCP クライアントは HTTP 経由で接続するため、これを
// お使いのサーバーのエンドポイントに向けてください。
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// ツールを一覧取得し、Claude API 用に変換します
$runner = $anthropic->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
model: 'claude-opus-5-5',
tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
);
echo $runner->runUntilDone(), "\n";
```
```ruby Ruby
require "mcp"
anthropic = Anthropic::Client.new
# MCP サーバーに接続する
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# ツールを一覧取得し、Claude API 用に変換する
runner = anthropic.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
final_message = runner.run_until_finished.last
puts final_message
```
### MCPプロンプトの使用
MCPプロンプトメッセージをClaude APIメッセージ形式に変換します。
```python Python
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)
```
```typescript TypeScript
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-opus-5-5",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response);
```
```csharp C#
var prompt = await mcpClient.GetPromptAsync("my-prompt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = BetaMcp.Messages(prompt.Messages),
}
);
Console.WriteLine(response);
```
```go Go
prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
if err != nil {
log.Fatal(err)
}
messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
for _, promptMessage := range prompt.Messages {
message, err := mcp.ToMessage(promptMessage)
if err != nil {
log.Fatal(err)
}
messages = append(messages, message)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
new McpSchema.GetPromptRequest("my-prompt", Map.of()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(BetaMcp.mcpMessages(prompt.messages()))
.build());
IO.println(response);
```
```php PHP
$prompt = $mcp->getPrompt('my-prompt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: array_map(BetaMcp::message(...), $prompt->messages),
model: 'claude-opus-5-5',
);
echo $response, "\n";
```
```ruby Ruby
prompt = mcp_client.get_prompt(name: "my-prompt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
)
puts response
```
### MCPリソースの使用
MCPリソースをメッセージに含めるコンテンツブロックに変換するか、アップロード用のファイルオブジェクトに変換します。
```python Python
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)
```
```typescript TypeScript
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// メッセージ内のコンテンツブロックとして
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
console.log(response);
// ファイルアップロードとして
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
console.log(uploaded.id);
```
```csharp C#
// メッセージ内のコンテンツブロックとして
var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = new BetaMessageParamContent(
[
BetaMcp.ResourceToContent(resource),
new BetaTextBlockParam { Text = "Summarize this document" },
]
),
},
],
}
);
Console.WriteLine(response);
// ファイルアップロードとして
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// リソースのファイル名と MIME タイプがアップロードに引き継がれるよう、
// ファイルパートを明示的に構築します。
var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
if (mediaType is not null)
{
file.ContentType = new(mediaType);
}
var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
Console.WriteLine(uploaded.ID);
```
```go Go
// メッセージ内のコンテンツブロックとして
resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
if err != nil {
log.Fatal(err)
}
block, err := mcp.ResourceToBlock(resource)
if err != nil {
log.Fatal(err)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
// ResourceToBlock は tool-result コンテンツのユニオン型を返します。メッセージの
// コンテンツは別のユニオン型なので、共通のバリアントを再ラップします
// （mcp.ToMessage も内部で同じ処理を行います）。
anthropic.BetaContentBlockParamUnion{
OfText: block.OfText,
OfImage: block.OfImage,
OfDocument: block.OfDocument,
},
anthropic.NewBetaTextBlock("Summarize this document"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
// ファイルアップロードとして
fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
if err != nil {
log.Fatal(err)
}
fileReader, err := mcp.ResourceToFile(fileResult)
if err != nil {
log.Fatal(err)
}
uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
if err != nil {
log.Fatal(err)
}
fmt.Println(uploaded.ID)
```
```java Java
// メッセージ内のコンテンツブロックとして
McpSchema.ReadResourceResult resource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));
List content =
new ArrayList<>(BetaMcp.mcpResourceContents(resource));
content.add(BetaContentBlockParam.ofText(
BetaTextBlockParam.builder().text("Summarize this document").build()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBetaContentBlockParams(content)
.build());
IO.println(response);
// ファイルアップロードとして
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// リソースのファイル名と MIME タイプがアップロードに引き継がれるよう、
// ファイルパートを明示的に構築します。
MultipartField.Builder fileField = MultipartField.builder()
.value(new ByteArrayInputStream(resourceFile.content()))
.filename(resourceFile.filename());
if (resourceFile.mimeType() != null) {
fileField.contentType(resourceFile.mimeType());
}
var uploaded = anthropic.files().upload(FileUploadParams.builder()
.file(fileField.build())
.build());
IO.println(uploaded.id());
```
```php PHP
// メッセージ内のコンテンツブロックとして
$resource = $mcp->readResource('file:///path/to/doc.txt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
BetaMcp::resourceToContent($resource),
['type' => 'text', 'text' => 'Summarize this document'],
],
],
],
model: 'claude-opus-5-5',
);
echo $response, "\n";
// ファイルアップロードとして
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# メッセージ内のコンテンツブロックとして
resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
*Anthropic::Mcp.resource_to_contents(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
)
puts response
# ファイルアップロードとして
file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
file = Anthropic::Mcp.resource_to_files(file_resource).first
uploaded_file = anthropic.files.upload(file: file)
puts uploaded_file.id
```
### エラー処理
MCPの値がClaude APIでサポートされていない場合、変換関数は`UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`)で失敗します（例外としてスローされるか、Goではエラーとして返されます）。これは、サポートされていないコンテンツタイプ、MIMEタイプ、またはリソースリンクで発生する可能性があります（リソースリンクは変換前にMCPクライアントで解決してください）。
## バッチリクエスト
[Message Batches API](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)リクエストに`mcp_servers`を含めることができます。Batches APIを通じたMCPツール呼び出しは、通常のMessages APIリクエストと同じ価格設定です。
## データ保持
MCPコネクタはZDR契約の対象外です。ツール定義や実行結果を含む、MCPサーバーと交換されるデータは、Anthropicの標準データ保持ポリシーに従って保持されます。
すべての機能にわたるZDR適格性については、[APIとデータ保持](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention)を参照してください。
## 移行ガイド
非推奨の`mcp-client-2025-04-04`ベータヘッダーを使用している場合は、このガイドに従って新しいバージョンに移行してください。
### 主な変更点
1. **新しいベータヘッダー:** `mcp-client-2025-04-04`から`mcp-client-2025-11-20`に変更
2. **ツール設定の移動:** ツール設定は、MCPサーバー定義ではなく、`tools`配列内のMCPToolsetオブジェクトに存在するようになりました
3. **より柔軟な設定:** 新しいパターンは、許可リスト化、拒否リスト化、およびツールごとの設定をサポートします
### 移行手順
**変更前（非推奨）:**
```json
{
"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"]
}
}
]
}
```
**変更後（現在）:**
```json
{
"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
}
}
}
]
}
```
### 一般的な移行パターン
| 旧パターン | 新パターン |
| ----------------------------------------- | -------------------------------------------------------------------- |
| `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
このバージョンは非推奨です。前述の[移行ガイド](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#migration-guide)を使用して`mcp-client-2025-11-20`に移行してください。
以前のバージョンのMCPコネクタでは、ツール設定をMCPサーバー定義に直接含めていました。
```json
{
"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`で許可リストパターンを使用してください |