Коннектор 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 доступен в Claude API, Claude Platform на AWS и Microsoft Foundry. В Microsoft Foundry коннектор MCP требует развёртывания с размещением у Anthropic. В настоящее время он недоступен в Amazon Bedrock и Google Cloud.



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

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

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



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

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
  "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:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk



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

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

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";



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

Преобразуйте инструменты MCP для использования с исполнителем инструментов 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 finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);



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

Преобразуйте сообщения подсказок 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-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);



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

Преобразуйте ресурсы 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-opus-4-8",
  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_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-4-8",
  "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-8",
  "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"]
      }
    }
  ]
}



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