MCP connector

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

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

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

Ограничения

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

Использование MCP connector в Messages API

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

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

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

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

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-6",
    "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"
      }
    ]
  }'

Конфигурация 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) поддерживает следующие поля:

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

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

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-6",
  "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 connector поддерживает передачу параметра 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 обратитесь к разделу Authorization в спецификации MCP.

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

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

Установка

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

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

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

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

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

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

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

import Anthropic from "@anthropic-ai/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-client-2025-04-04, следуйте этому руководству для миграции на новую версию.

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

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

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

До (устарело):

{
  "model": "claude-opus-4-6",
  "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-6",
  "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 connector включала конфигурацию инструментов непосредственно в определение 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"]
      }
    }
  ]
}

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