Коннектор MCP

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

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

• Прямая интеграция API: Подключайтесь к серверам MCP без реализации клиента MCP
• Поддержка вызова инструментов: Получайте доступ к инструментам MCP через Messages API
• Гибкая конфигурация инструментов: Включайте все инструменты, составляйте список разрешённых инструментов или запрещайте нежелательные инструменты
• Конфигурация для каждого инструмента: Настраивайте отдельные инструменты с пользовательскими параметрами
• Аутентификация OAuth: Поддержка токенов OAuth Bearer для аутентифицированных серверов
• Несколько серверов: Подключайтесь к нескольким серверам MCP в одном запросе

Ограничения

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

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

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 на стороне клиента (TypeScript)

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

Установка

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

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();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

Использование подсказок 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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

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

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

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
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 не охватывается соглашениями 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-7",
  "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-7",
  "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"]
      }
    }
  ]
}

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