Claude Platform Docs

Коннектор MCP

Подключайтесь к удалённым серверам MCP напрямую из Messages API без клиента MCP, а также добавляйте инструменты в список разрешённых, список запрещённых или настраивайте отдельные инструменты.

Использование зависит от продукта

Messages API
Передавайте mcp_servers и соответствующий mcp_toolset в tools в каждом запросе.
Managed Agents
Объявите MCP-серверы в агенте. Каждая сессия предоставляет учётные данные через ссылку на хранилище, поэтому секреты не попадают в определение агента.

Функция коннектора «Model Context Protocol», или MCP, в Claude позволяет подключаться к удалённым серверам MCP напрямую из Messages API без отдельного клиента MCP.

Ключевые возможности

  • Прямая интеграция с 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 использует инструменты для общих рекомендаций и примеров формулировок.

Ограничения

  • Из набора возможностей спецификации MCP в настоящее время поддерживаются только вызовы инструментов.
  • Сервер должен быть публично доступен по HTTP (поддерживаются транспорты Streamable HTTP и SSE). Локальные серверы STDIO нельзя подключить напрямую.

Использование коннектора MCP в Messages API

Коннектор MCP использует два компонента:

  1. Определение сервера MCP (массив mcp_servers): задаёт параметры подключения к серверу (URL, аутентификация)
  2. Набор инструментов MCP (массив tools): определяет, какие инструменты включить и как их настроить

Базовый пример

В этом примере включаются все инструменты сервера MCP с конфигурацией по умолчанию:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

Конфигурация сервера MCP

Каждый сервер MCP в массиве mcp_servers задаёт параметры подключения:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Описание полей

СвойствоТипОбязательноОписание
typestringДаВ настоящее время поддерживается только url.
urlstringДаURL сервера MCP. Должен начинаться с https://.
namestringДаУникальный идентификатор этого сервера MCP. На него должен ссылаться ровно один MCPToolset в массиве tools.
authorization_tokenstringНетТокен авторизации 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
    }
  }
}

Описание полей

СвойствоТипОбязательноОписание
typestringДаДолжно быть mcp_toolset.
mcp_server_namestringДаДолжно совпадать с именем сервера, определённого в массиве mcp_servers.
default_configobjectНетКонфигурация по умолчанию, применяемая ко всем инструментам в этом наборе. Конфигурации отдельных инструментов в configs переопределяют эти значения по умолчанию.
configsobjectНетПереопределения конфигурации для отдельных инструментов. Ключи — имена инструментов; значения — объекты конфигурации.
cache_controlobjectНетКонфигурация точки останова кэша для кэширования подсказок для этого набора инструментов.

С бета-заголовком mcp-client-2026-09-15 MCPToolset также принимает tools — закреплённую копию списка инструментов сервера. См. раздел Закрепление списка инструментов сервера MCP.

Параметры конфигурации инструментов

Каждый инструмент (настроенный в default_config или в configs) поддерживает следующие поля:

СвойствоТипПо умолчаниюОписание
enabledbooleantrueВключён ли этот инструмент.
defer_loadingbooleanfalseЕсли true, описание инструмента изначально не отправляется модели. Используется с инструментом поиска инструментов.

Полный каталог инструментов, предоставляемых Anthropic, и необязательных свойств, таких как defer_loading, см. в справочнике по инструментам. Для поиска по большим наборам инструментов см. инструмент поиска инструментов.

Объединение конфигураций

Значения конфигурации объединяются со следующим приоритетом (от высшего к низшему):

  1. Настройки конкретного инструмента в configs
  2. default_config на уровне набора
  3. Системные значения по умолчанию

Пример:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Результат:

  • search_events: enabled: false (из configs), defer_loading: true (из default_config)
  • Все остальные инструменты: enabled: true (системное значение по умолчанию), defer_loading: true (из default_config)

Распространённые шаблоны конфигурации

Включить все инструменты с конфигурацией по умолчанию

Самый простой шаблон: включить все инструменты сервера:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Список разрешённых: включить только определённые инструменты

Установите enabled: false по умолчанию, затем явно включите конкретные инструменты:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

Список запрещённых: отключить определённые инструменты

Включите все инструменты по умолчанию, затем явно отключите нежелательные. Добавление инструментов записи или деструктивных инструментов в список запрещённых рекомендуется при создании ассистентов только для чтения или когда вы хотите добавить шаг подтверждения человеком перед изменением состояния:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

Смешанный: список разрешённых с настройкой отдельных инструментов

Сочетайте список разрешённых с пользовательской конфигурацией для каждого инструмента:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

В этом примере:

  • search_events включён с defer_loading: false.
  • list_events включён с defer_loading: true (унаследовано из default_config).
  • Все остальные инструменты отключены.

Правила валидации

API применяет следующие правила валидации:

  • Сервер должен существовать: mcp_server_name в MCPToolset должен совпадать с сервером, определённым в массиве mcp_servers.
  • Сервер должен использоваться: на каждый сервер MCP, определённый в mcp_servers, должен ссылаться ровно один MCPToolset.
  • Уникальный набор инструментов для каждого сервера: на каждый сервер MCP может ссылаться только один MCPToolset.
  • Неизвестные имена инструментов: если имя инструмента в configs отсутствует на сервере MCP, в журнал бэкенда записывается предупреждение, но ошибка не возвращается (набор доступных инструментов на серверах MCP может меняться динамически).

Типы содержимого ответа

Когда Claude использует инструменты MCP, ответ включает два новых типа блоков содержимого:

Блок использования инструмента MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Блок результата инструмента MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

Закрепление списка инструментов сервера MCP (бета)

Сервер MCP может изменить свои инструменты в любой момент. С бета-заголовком mcp-client-2026-09-15 API записывает список инструментов, возвращаемый каждым сервером, и вы можете закрепить этот список. Благодаря этому изменение инструментов сервера не меняет того, что получает Claude, посреди диалога.

Этот заголовок включает всё, что включает mcp-client-2025-11-20. На платформах, которые его принимают, отправляйте его вместо того заголовка.

Когда API запрашивает у сервера MCP его инструменты при формировании ответа, ответ начинается с блока mcp_tool_listing для этого сервера — по одному блоку для каждого опрошенного сервера:

{
  "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:

{
  "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 не обращается к серверу:

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

client = anthropic.Anthropic()

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

# Первый запрос: набор инструментов не закреплён, поэтому API запрашивает у сервера
# его инструменты, и ответ начинается с блока mcp_tool_listing.
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

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

# Закрепите список: скопируйте инструменты из блока в набор инструментов. API использует
# именно эти записи и больше не обращается к серверу.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# При закреплённом наборе инструментов в ответе нет блока mcp_tool_listing.
print([block.type for block in second.content])

Если дополнительно использовать бета-заголовок inline-tools-2026-09-15, можно добавить сервер MCP посреди разговора. См. раздел Добавление сервера MCP в середине разговора.

Несколько серверов MCP

Вы можете подключиться к нескольким серверам MCP, включив несколько определений серверов в mcp_servers и соответствующий MCPToolset для каждого из них в массив tools:

{
  "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 вместе с инструментом поиска инструментов, чтобы для каждого запроса предлагались только релевантные инструменты.

Аутентификация

Для серверов MCP, требующих аутентификации OAuth, вам потребуется получить токен доступа. Бета-версия коннектора MCP поддерживает передачу параметра authorization_token в определении сервера MCP. Ожидается, что потребители API самостоятельно выполняют процесс OAuth и получают токен доступа до выполнения вызова API, а также обновляют токен по мере необходимости.

Получение токена доступа для тестирования

MCP inspector может провести вас через процесс получения токена доступа для целей тестирования.

  1. Запустите inspector следующей командой. На вашем компьютере должен быть установлен Node.js.

    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.

Использование токена доступа

После получения токена доступа его можно использовать в конфигурации сервера 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

Если вы управляете собственным подключением клиента MCP (например, с локальными серверами stdio, подсказками MCP или ресурсами MCP), SDK предоставляет вспомогательные функции, которые преобразуют типы MCP в типы Claude API и обратно. Это избавляет от необходимости писать код ручного преобразования при использовании MCP SDK для вашего языка (например, TypeScript MCP SDK) вместе с Anthropic SDK.

Установка

Установите Anthropic SDK и MCP SDK:

Вспомогательные функции MCP входят в дополнительный пакет mcp, для которого требуется Python 3.10 или новее:

pip install "anthropic[mcp]"

Доступные вспомогательные функции

Импортируйте вспомогательные функции для вашего языка:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)
Вспомогательная функцияОписание
async_mcp_tool(tool, mcp_client)Преобразует инструменты MCP в инструменты Claude API для использования с client.beta.messages.tool_runner()
mcp_message(message)Преобразует сообщения подсказок MCP в формат сообщений Claude API
mcp_resource_to_content(resource)Преобразует ресурс MCP в блок содержимого Claude API
mcp_resource_to_file(resource)Преобразует ресурс MCP в файловый объект для загрузки

Использование инструментов MCP

Преобразуйте инструменты MCP для использования с исполнителем инструментов SDK, который автоматически обрабатывает выполнение инструментов:

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Подключение к серверу MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Получение списка инструментов и их преобразование для Claude API
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

Использование подсказок MCP

Преобразуйте сообщения подсказок MCP в формат сообщений Claude API:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

Использование ресурсов MCP

Преобразуйте ресурсы MCP в блоки содержимого для включения в сообщения или в файловые объекты для загрузки:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Как блок содержимого в сообщении
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Как загрузка файла
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Обработка ошибок

Функции преобразования завершаются с ошибкой UnsupportedMCPValueError, если значение MCP не поддерживается Claude API (выбрасывается исключение, а в Go ошибка возвращается). Это может произойти с неподдерживаемыми типами содержимого, MIME-типами или ссылками на ресурсы (разрешайте ссылки на ресурсы с помощью клиента MCP перед преобразованием).

Пакетные запросы

Вы можете включать mcp_servers в запросы Message Batches API. Вызовы инструментов MCP через Batches API тарифицируются так же, как и в обычных запросах Messages API.

Хранение данных

Коннектор MCP не подпадает под соглашения ZDR. Данные, которыми обмениваются с серверами MCP, включая определения инструментов и результаты выполнения, хранятся в соответствии со стандартной политикой хранения данных Anthropic.

Руководство по миграции

Если вы используете устаревший бета-заголовок mcp-client-2025-04-04, следуйте этому руководству для перехода на новую версию.

Ключевые изменения

  1. Новый бета-заголовок: замените mcp-client-2025-04-04 на mcp-client-2025-11-20.
  2. Конфигурация инструментов перенесена: теперь конфигурация инструментов находится в массиве tools в виде объектов MCPToolset, а не в определении сервера MCP.
  3. Более гибкая конфигурация: новый подход поддерживает списки разрешённых, списки запрещённых и настройку отдельных инструментов.

Шаги миграции

До (устаревшая версия):

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

После (текущая версия):

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Распространённые шаблоны миграции

Старый шаблонНовый шаблон
Нет tool_configuration (все инструменты включены)MCPToolset без default_config или configs
tool_configuration.enabled: falseMCPToolset с default_config.enabled: false
tool_configuration.allowed_tools: [...]MCPToolset с default_config.enabled: false и конкретными инструментами, включёнными в configs

Устаревшая версия: mcp-client-2025-04-04

Предыдущая версия коннектора MCP включала конфигурацию инструментов непосредственно в определение сервера MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Описание устаревших полей

СвойствоТипОписание
tool_configurationobjectУстарело: используйте вместо этого MCPToolset в массиве tools
tool_configuration.enabledbooleanУстарело: используйте default_config.enabled в MCPToolset
tool_configuration.allowed_toolsarrayУстарело: используйте шаблон списка разрешённых с configs в MCPToolset

Доступность

Коннектор MCP
Статус
Бета
API
  • Messages API требуется либо или
  • Managed Agents
Модели
  • Все модели

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/messages с mcp_servers
Нулевое хранение данныхНе допускается

Данные хранятся в соответствии со стандартной политикой. Подробнее

HIPAAНе допускается

Эта страница была полезной?