Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Функция коннектора Model Context Protocol (MCP) Claude позволяет подключаться к удалённым MCP серверам непосредственно из Messages API без отдельного MCP клиента.
Текущая версия: Эта функция требует бета-заголовок: "anthropic-beta": "mcp-client-2025-11-20"
Предыдущая версия (mcp-client-2025-04-04) устарела. См. документацию устаревшей версии ниже.
Коннектор 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-sonnet-4-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"
}
]
}'Каждый 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-sonnet-4-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
}
}
]
}Для 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-client-2025-04-04, следуйте этому руководству для миграции на новую версию.
mcp-client-2025-04-04 на mcp-client-2025-11-20tools как объекты MCPToolset, а не в определении MCP сервераДо (устарело):
{
"model": "claude-sonnet-4-5",
"max_tokens": 1000,
"messages": [...],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}После (текущее):
{
"model": "claude-sonnet-4-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-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 |