Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Функция MCP коннектора (Model Context Protocol) в Claude позволяет подключаться к удалённым MCP серверам напрямую из Messages API без отдельного MCP клиента.
Текущая версия: Эта функция требует бета-заголовка: "anthropic-beta": "mcp-client-2025-11-20"
Предыдущая версия (mcp-client-2025-04-04) устарела. См. документацию устаревшей версии ниже.
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
Was this page helpful?
MCP коннектор использует два компонента:
mcp_servers): Определяет детали подключения к серверу (URL, аутентификация)tools): Настраивает, какие инструменты включить и как их конфигурироватьЭтот пример включает все инструменты с MCP сервера с конфигурацией по умолчанию:
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-4-6",
"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"
}
]
}'Каждый MCP сервер в массиве mcp_servers определяет детали подключения:
{
"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 сервером. См. спецификацию MCP. |
MCPToolset находится в массиве tools и настраивает, какие инструменты с MCP сервера включены и как они должны быть сконфигурированы.
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}| Свойство | Тип | Обязательное | Описание |
|---|---|---|---|
type | string | Да | Должно быть "mcp_toolset" |
mcp_server_name | string | Да | Должно совпадать с именем сервера, определённым в массиве mcp_servers |
default_config | object | Нет | Конфигурация по умолчанию, применяемая ко всем инструментам в этом наборе. Индивидуальные конфигурации инструментов в configs переопределяют эти значения по умолчанию. |
configs | object | Нет | Переопределения конфигурации для отдельных инструментов. Ключи — имена инструментов, значения — объекты конфигурации. |
cache_control | object | Нет | Конфигурация точки разрыва кэша для этого набора инструментов |
Каждый инструмент (настроенный в default_config или в configs) поддерживает следующие поля:
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
enabled | boolean | true | Включён ли этот инструмент |
defer_loading | boolean | false | Если true, описание инструмента изначально не отправляется модели. Используется с инструментом поиска инструментов. |
Значения конфигурации объединяются с таким приоритетом (от высшего к низшему):
configsdefault_config на уровне набораПример:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}Результат:
search_events: enabled: false (из configs), defer_loading: true (из default_config)enabled: true (системное значение по умолчанию), defer_loading: true (из default_config)Простейший шаблон — включить все инструменты с сервера:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}Установите enabled: false по умолчанию, затем явно включите конкретные инструменты:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}Включите все инструменты по умолчанию, затем явно отключите ненужные:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}Объедините список разрешённых с индивидуальной конфигурацией для каждого инструмента:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}В этом примере:
search_events включён с defer_loading: falselist_events включён с defer_loading: true (унаследовано из default_config)API применяет следующие правила валидации:
mcp_server_name в MCPToolset должно совпадать с сервером, определённым в массиве mcp_serversmcp_servers, должен быть указан ровно в одном MCPToolsetconfigs не существует на MCP сервере, в бэкенде записывается предупреждение, но ошибка не возвращается (MCP серверы могут иметь динамическую доступность инструментов)Когда Claude использует MCP инструменты, ответ будет включать два новых типа блоков содержимого:
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}Вы можете подключаться к нескольким MCP серверам, включив несколько определений серверов в mcp_servers и соответствующий MCPToolset для каждого в массиве tools:
{
"model": "claude-opus-4-6",
"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
}
}
]
}Для MCP серверов, требующих OAuth аутентификации, вам необходимо получить токен доступа. Бета-версия MCP коннектора поддерживает передачу параметра authorization_token в определении MCP сервера.
Ожидается, что потребители API самостоятельно обработают OAuth поток и получат токен доступа до выполнения вызова API, а также будут обновлять токен по мере необходимости.
Инспектор MCP может провести вас через процесс получения токена доступа для тестирования.
Запустите инспектор следующей командой. На вашем компьютере должен быть установлен Node.js.
npx @modelcontextprotocol/inspectorНа боковой панели слева для "Transport type" выберите "SSE" или "Streamable HTTP".
Введите URL MCP сервера.
В правой области нажмите кнопку "Open Auth Settings" после "Need to configure authentication?".
Нажмите "Quick OAuth Flow" и авторизуйтесь на экране OAuth.
Следуйте шагам в разделе "OAuth Flow Progress" инспектора и нажимайте "Continue" до достижения "Authentication complete".
Скопируйте значение access_token.
Вставьте его в поле authorization_token в конфигурации вашего MCP сервера.
После получения токена доступа с помощью описанного выше OAuth потока вы можете использовать его в конфигурации вашего MCP сервера:
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}Подробные объяснения OAuth потока см. в разделе Authorization спецификации MCP.
Если вы управляете собственным MCP клиентским подключением (например, с локальными stdio серверами, MCP промптами или MCP ресурсами), TypeScript SDK предоставляет вспомогательные функции для преобразования между типами MCP и типами Claude API. Это устраняет необходимость в ручном коде преобразования при использовании MCP SDK совместно с Anthropic SDK.
Эти вспомогательные функции в настоящее время доступны только в TypeScript SDK.
Используйте параметр API mcp_servers, когда у вас есть удалённые серверы, доступные по URL, и вам нужна только поддержка инструментов. Если вы используете Agent SDK, MCP подключения управляются автоматически. Используйте клиентские вспомогательные функции, когда вам нужны локальные серверы, промпты, ресурсы или больший контроль над подключением с базовым SDK.
Установите Anthropic SDK и MCP SDK:
npm install @anthropic-ai/sdk @modelcontextprotocol/sdkИмпортируйте вспомогательные функции из бета-пространства имён:
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";| Вспомогательная функция | Описание |
|---|---|
mcpTools(tools, mcpClient) | Преобразует MCP инструменты в инструменты Claude API для использования с client.beta.messages.toolRunner() |
mcpMessages(messages) | Преобразует сообщения MCP промпта в формат сообщений Claude API |
mcpResourceToContent(resource) | Преобразует MCP ресурс в блок содержимого Claude API |
mcpResourceToFile(resource) | Преобразует MCP ресурс в объект файла для загрузки |
Преобразуйте MCP инструменты для использования с исполнителем инструментов SDK, который автоматически обрабатывает выполнение инструментов:
import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } 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();
const runner = await anthropic.beta.messages.toolRunner({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClient)
});Преобразуйте сообщения MCP промпта в формат сообщений Claude API:
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-sonnet-4-6",
max_tokens: 1024,
messages: mcpMessages(messages)
});Преобразуйте MCP ресурсы в блоки содержимого для включения в сообщения или в объекты файлов для загрузки:
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// Как блок содержимого в сообщении
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
// Как загрузка файла
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });Функции преобразования выбрасывают UnsupportedMCPValueError, если значение MCP не поддерживается Claude API. Это может произойти с неподдерживаемыми типами содержимого, MIME типами или ссылками на ресурсы, не являющимися HTTP.
MCP коннектор не охватывается соглашениями ZDR. Данные, передаваемые через MCP серверы, включая определения инструментов и результаты выполнения, хранятся в соответствии со стандартной политикой хранения данных Anthropic.
Информацию о соответствии ZDR для всех функций см. в разделе API и хранение данных.
Если вы используете устаревший бета-заголовок mcp-client-2025-04-04, следуйте этому руководству для перехода на новую версию.
mcp-client-2025-04-04 на mcp-client-2025-11-20tools в виде объектов MCPToolset, а не в определении MCP сервераДо (устаревший вариант):
{
"model": "claude-opus-4-6",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}После (текущий вариант):
{
"model": "claude-opus-4-6",
"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-11-20, используя руководство по миграции выше.
Предыдущая версия MCP коннектора включала конфигурацию инструментов непосредственно в определение MCP сервера:
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}| Свойство | Тип | Описание |
|---|---|---|
tool_configuration | object | Устарело: Используйте MCPToolset в массиве tools |
tool_configuration.enabled | boolean | Устарело: Используйте default_config.enabled в MCPToolset |
tool_configuration.allowed_tools | array | Устарело: Используйте шаблон списка разрешённых с configs в MCPToolset |