Коннектор 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, через системную подсказку. См. Когда 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",
    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
    }
  }
}



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



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

Каждый инструмент (настроенный в 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_servers и соответствующий MCPToolset для каждого в массив tools:

{
  "model": "claude-opus-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 может провести вас через процесс получения токена доступа для целей тестирования.

1. Запустите инспектор следующей командой. На вашем компьютере должен быть установлен 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» инспектора и нажимайте «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 см. в разделе об авторизации спецификации MCP.



Вспомогательные функции MCP на стороне клиента

Если вы управляете собственным клиентским подключением MCP (например, с локальными серверами stdio, подсказками MCP или ресурсами MCP), SDK предоставляют вспомогательные функции, которые преобразуют типы MCP в типы Claude API и обратно. Это избавляет от ручного кода преобразования при использовании SDK MCP для вашего языка (например, 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",
                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",
    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,
)

# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# As a file upload
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 вспомогательные функции возвращают UnsupportedValueError; в Java и C# они выбрасывают AnthropicInvalidDataException). Это может произойти с неподдерживаемыми типами содержимого, 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",
  "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",
  "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"]
      }
    }
  ]
}



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