Коннектор 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"
}

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

Конфигурация набора инструментов 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
    }
  }
}

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

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

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

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

Полный каталог инструментов, предоставляемых 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 записывает список инструментов, возвращаемый каждым сервером, и позволяет закрепить его, чтобы сервер, изменивший свои инструменты, не менял то, что видит Claude, посреди разговора. Он включает всё, что включает mcp-client-2025-11-20, поэтому отправляйте его вместо того заголовка. Он доступен в Claude API.

Когда 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.

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

Получив токен доступа с помощью любого из описанных выше процессов 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

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

Установка

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

pip install "anthropic[mcp]"

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

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

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

Имена вспомогательных функций и точные сигнатуры следуют соглашениям каждого языка; в этой таблице показаны формы для TypeScript:

Использование инструментов 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.

Сведения о применимости ZDR ко всем функциям см. в разделе API и хранение данных.

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

Если вы используете устаревший бета-заголовок 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
        }
      }
    }
  ]
}

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

Устаревшая версия: 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"]
      }
    }
  ]
}

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

Compatibility