---
title: Коннектор MCP
url: https://platform.claude.com/docs/ru/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
---
Функция коннектора Model Context Protocol, или MCP, в Claude позволяет подключаться к удалённым серверам MCP напрямую из Messages API без отдельного клиента MCP.
Предыдущая версия этой функции (`mcp-client-2025-04-04`) устарела. См. [Устаревшая версия: mcp-client-2025-04-04](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
## Ключевые возможности
* **Прямая интеграция с API:** подключайтесь к серверам MCP без реализации клиента MCP
* **Поддержка вызова инструментов:** получайте доступ к инструментам MCP через Messages API
* **Гибкая настройка инструментов:** включайте все инструменты, добавляйте конкретные инструменты в список разрешённых или нежелательные инструменты в список запрещённых
* **Настройка отдельных инструментов:** настраивайте отдельные инструменты с пользовательскими параметрами
* **Аутентификация OAuth:** поддержка токенов OAuth Bearer для серверов с аутентификацией
* **Несколько серверов:** подключайтесь к нескольким серверам MCP в одном запросе
## Когда Claude использует инструменты MCP
После подключения сервера MCP Claude вызывает его инструменты, когда запрос пользователя соответствует описанной возможности инструмента — либо явно («найди в Jira открытые баги»), либо неявно («что блокирует релиз?» при подключённом сервере Jira).
Claude **не** вызывает инструмент MCP для вопросов общего характера о подключённом сервисе. На вопрос «как работают базы данных Notion?» при подключённом сервере Notion ответ даётся напрямую; вопрос «что находится в моей базе данных Projects?» запускает инструмент.
Вы можете управлять тем, насколько охотно Claude вызывает инструменты MCP, через вашу «system prompt» (системную подсказку). См. [Когда Claude использует инструменты](https://platform.claude.com/docs/ru/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 нельзя подключить напрямую.
## Использование коннектора MCP в Messages API
Коннектор MCP использует два компонента:
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 в массиве `mcp_servers` задаёт параметры подключения:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Описание полей
| Свойство | Тип | Обязательно | Описание |
| --------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Да | В настоящее время поддерживается только "url". |
| `url` | string | Да | URL сервера MCP. Должен начинаться с https\://. |
| `name` | string | Да | Уникальный идентификатор этого сервера MCP. На него должен ссылаться ровно один MCPToolset в массиве `tools`. |
| `authorization_token` | string | Нет | Токен авторизации OAuth, если он требуется сервером MCP. См. раздел [Аутентификация](https://platform.claude.com/docs/ru/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/ru/build-with-claude/prompt-caching) для этого набора инструментов. |
С бета-заголовком `mcp-client-2026-09-15` MCPToolset также принимает `tools` — закреплённую копию списка инструментов сервера. См. раздел [Закрепление списка инструментов сервера MCP](https://platform.claude.com/docs/ru/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/ru/agents-and-tools/tool-use/tool-search-tool). |
Полный каталог инструментов, предоставляемых Anthropic, и необязательных свойств, таких как `defer_loading`, см. в [справочнике по инструментам](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference). Для поиска по большим наборам инструментов см. [инструмент поиска инструментов](https://platform.claude.com/docs/ru/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 применяет следующие правила валидации:
* **Сервер должен существовать:** `mcp_server_name` в MCPToolset должен совпадать с сервером, определённым в массиве `mcp_servers`
* **Сервер должен использоваться:** на каждый сервер MCP, определённый в `mcp_servers`, должен ссылаться ровно один MCPToolset
* **Уникальный набор инструментов для каждого сервера:** на каждый сервер MCP может ссылаться только один MCPToolset
* **Неизвестные имена инструментов:** если имя инструмента в `configs` не существует на сервере MCP, на стороне бэкенда записывается предупреждение, но ошибка не возвращается (серверы MCP могут иметь динамическую доступность инструментов)
## Типы содержимого ответа
Когда Claude использует инструменты MCP, ответ включает два новых типа блоков содержимого:
### Блок использования инструмента 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` для этого сервера — по одному блоку для каждого опрошенного сервера:
```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` из блока в поле `tools` набора MCPToolset этого сервера. Тогда 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`.
В следующем примере отправляется один запрос с незакреплённым набором инструментов, возвращённый список копируется в поле `tools` набора, и запрос отправляется снова. Во втором ответе нет блока `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
# заменяет массив tools в теле запроса. 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/ru/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## Несколько серверов MCP
Вы можете подключиться к нескольким серверам MCP, включив несколько определений серверов в `mcp_servers` и соответствующий MCPToolset для каждого из них в массив `tools`:
```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 выбирает их на основе имён и описаний. Чёткие, конкретные описания инструментов повышают точность выбора. Для больших наборов инструментов (десятки инструментов на нескольких серверах) рассмотрите возможность включения [`defer_loading`](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector#tool-configuration-options) вместе с [инструментом поиска инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool), чтобы для каждого запроса отображались только релевантные инструменты.
## Аутентификация
Для серверов MCP, требующих аутентификации OAuth, вам потребуется получить токен доступа. Бета-версия коннектора MCP поддерживает передачу параметра `authorization_token` в определении сервера MCP. Ожидается, что потребители API самостоятельно выполняют процесс OAuth и получают токен доступа до выполнения вызова API, а также обновляют токен по мере необходимости.
### Получение токена доступа для тестирования
MCP inspector может провести вас через процесс получения токена доступа для целей тестирования.
1. Запустите inspector следующей командой. На вашем компьютере должен быть установлен Node.js.
```bash
npx @modelcontextprotocol/inspector
```
2. На боковой панели слева для **Transport type** выберите **SSE** или **Streamable HTTP**.
3. Введите URL сервера MCP.
4. В правой области нажмите **Open Auth Settings** после **Need to configure authentication?**.
5. Нажмите **Quick OAuth Flow** и авторизуйтесь на экране OAuth.
6. Следуйте шагам в разделе **OAuth Flow Progress** в inspector и нажимайте **Continue**, пока не достигнете **Authentication complete**.
7. Скопируйте значение `access_token`.
8. Вставьте его в поле `authorization_token` в конфигурации вашего сервера MCP.
### Использование токена доступа
Получив токен доступа с помощью любого из описанных выше процессов OAuth, вы можете использовать его в конфигурации сервера MCP:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
Подробное описание процесса OAuth см. в [разделе Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) спецификации MCP.
## Клиентские вспомогательные функции MCP
Если вы управляете собственным подключением клиента MCP (например, с локальными серверами stdio, подсказками MCP или ресурсами MCP), SDK предоставляет вспомогательные функции, которые преобразуют типы MCP в типы Claude API и обратно. Это избавляет от необходимости писать код ручного преобразования при использовании MCP SDK для вашего языка (например, [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)) вместе с Anthropic SDK.
Используйте [параметр API `mcp_servers`](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api), если у вас есть удалённые серверы, доступные по URL, и вам нужна только поддержка инструментов. Используйте клиентские вспомогательные функции, если вам нужны локальные серверы, подсказки, ресурсы или больший контроль над подключением с помощью базового 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
```
Вспомогательные функции находятся в подпакете `mcp` Go SDK, который основан на [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`](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 в инструменты Claude API для использования с `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()`) |
| `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
Преобразуйте инструменты MCP для использования с [исполнителем инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner) SDK, который автоматически обрабатывает выполнение инструментов:
```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();
// Тип возвращаемого значения callTool в MCP SDK всё ещё включает устаревшую форму результата,
// которую 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();
// Раннер выдаёт одно сообщение на каждый ход ассистента; последнее — итоговый ответ
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. MCP-клиент на PHP подключается по 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
```
### Обработка ошибок
Функции преобразования завершаются ошибкой `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`), если значение MCP не поддерживается Claude API (ошибка выбрасывается как исключение, а в Go возвращается как значение ошибки). Это может произойти с неподдерживаемыми типами содержимого, MIME-типами или ссылками на ресурсы (разрешайте ссылки на ресурсы с помощью вашего клиента MCP перед преобразованием).
## Пакетные запросы
Вы можете включать `mcp_servers` в запросы [Message Batches API](https://platform.claude.com/docs/ru/build-with-claude/batch-processing). Вызовы инструментов MCP через Batches API тарифицируются так же, как и в обычных запросах Messages API.
## Хранение данных
Коннектор MCP не подпадает под соглашения ZDR. Данные, которыми обмениваются с серверами MCP, включая определения инструментов и результаты выполнения, хранятся в соответствии со стандартной политикой хранения данных Anthropic.
Сведения о применимости ZDR ко всем функциям см. в разделе [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
## Руководство по миграции
Если вы используете устаревший бета-заголовок `mcp-client-2025-04-04`, следуйте этому руководству для перехода на новую версию.
### Ключевые изменения
1. **Новый бета-заголовок:** замените `mcp-client-2025-04-04` на `mcp-client-2025-11-20`
2. **Конфигурация инструментов перенесена:** конфигурация инструментов теперь находится в массиве `tools` в виде объектов MCPToolset, а не в определении сервера MCP
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` (все инструменты включены) | MCPToolset без `default_config` или `configs` |
| `tool_configuration.enabled: false` | MCPToolset с `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset с `default_config.enabled: false` и конкретными инструментами, включёнными в `configs` |
## Устаревшая версия: mcp-client-2025-04-04
Эта версия устарела. Перейдите на `mcp-client-2025-11-20`, используя приведённое выше [руководство по миграции](https://platform.claude.com/docs/ru/agents-and-tools/mcp-connector#migration-guide).
Предыдущая версия коннектора 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 | **Устарело:** используйте вместо этого MCPToolset в массиве `tools` |
| `tool_configuration.enabled` | boolean | **Устарело:** используйте `default_config.enabled` в MCPToolset |
| `tool_configuration.allowed_tools` | array | **Устарело:** используйте шаблон списка разрешённых с `configs` в MCPToolset |