Руководства

Подключение к внешним инструментам с помощью MCP

Настройте серверы MCP для расширения вашего агента внешними инструментами. Охватывает типы транспорта, поиск инструментов для больших наборов инструментов, аутентификацию и обработку ошибок.

Model Context Protocol (MCP) — это открытый стандарт для подключения AI-агентов к внешним инструментам и источникам данных. С помощью MCP ваш агент может запрашивать базы данных, интегрироваться с API, такими как Slack и GitHub, и подключаться к другим сервисам без написания пользовательских реализаций инструментов.

Серверы MCP могут работать как локальные процессы, подключаться через HTTP или выполняться непосредственно в приложении SDK.

Быстрый старт

Этот пример подключается к серверу MCP документации Claude Code с использованием HTTP-транспорта и использует allowedTools с подстановочным символом для разрешения всех инструментов с сервера.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Агент подключается к серверу документации, ищет информацию о хуках и возвращает результаты.

Добавление сервера MCP

Вы можете настроить серверы MCP в коде при вызове query() или в файле .mcp.json, который SDK загружает автоматически.

В коде

Передайте серверы MCP непосредственно в опции mcpServers:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Из файла конфигурации

Создайте файл .mcp.json в корне вашего проекта. SDK загружает его автоматически:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Разрешение инструментов MCP

Инструменты MCP требуют явного разрешения перед тем, как Claude сможет их использовать. Без разрешения Claude увидит, что инструменты доступны, но не сможет их вызывать.

Соглашение об именовании инструментов

Инструменты MCP следуют шаблону именования mcp__<server-name>__<tool-name>. Например, сервер GitHub с именем "github" и инструментом list_issues становится mcp__github__list_issues.

Предоставление доступа с помощью allowedTools

Используйте allowedTools для указания, какие инструменты MCP может использовать Claude:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: [
    "mcp__github__*",              // All tools from the github server
    "mcp__db__query",              // Only the query tool from db server
    "mcp__slack__send_message"     // Only send_message from slack server
  ]
}

Подстановочные символы (*) позволяют разрешить все инструменты с сервера без перечисления каждого отдельно.

Альтернатива: изменение режима разрешений

Вместо перечисления разрешённых инструментов вы можете изменить режим разрешений для предоставления более широкого доступа:

permissionMode: "acceptEdits": автоматически одобряет использование инструментов (всё ещё запрашивает подтверждение для деструктивных операций)
permissionMode: "bypassPermissions": пропускает все запросы безопасности, включая деструктивные операции, такие как удаление файлов или выполнение команд оболочки. Используйте с осторожностью, особенно в production. Этот режим распространяется на подагентов, порождённых инструментом Task.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // No need for allowedTools
}

Дополнительные сведения см. в разделе Разрешения.

Обнаружение доступных инструментов

Чтобы увидеть, какие инструменты предоставляет сервер MCP, проверьте документацию сервера или подключитесь к серверу и проверьте сообщение инициализации system:

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

Типы транспорта

Серверы MCP взаимодействуют с вашим агентом, используя различные протоколы транспорта. Проверьте документацию сервера, чтобы узнать, какой транспорт он поддерживает:

Если в документации указана команда для запуска (например, npx @modelcontextprotocol/server-github), используйте stdio
Если в документации указан URL, используйте HTTP или SSE
Если вы создаёте свои собственные инструменты в коде, используйте сервер MCP SDK

Серверы stdio

Локальные процессы, которые взаимодействуют через stdin/stdout. Используйте это для серверов MCP, которые вы запускаете на одной машине:

Серверы HTTP/SSE

Используйте HTTP или SSE для облачных серверов MCP и удалённых API:

Для HTTP (без потоковой передачи) используйте "type": "http" вместо этого.

Серверы MCP SDK

Определите пользовательские инструменты непосредственно в коде приложения вместо запуска отдельного процесса сервера. Дополнительные сведения о реализации см. в руководстве по пользовательским инструментам.

Поиск инструментов MCP

Когда у вас настроено много инструментов MCP, определения инструментов могут потребить значительную часть вашего контекстного окна. Поиск инструментов MCP решает эту проблему, динамически загружая инструменты по требованию вместо предварительной загрузки всех.

Как это работает

Поиск инструментов работает в режиме auto по умолчанию. Он активируется, когда описания инструментов MCP потребляют более 10% контекстного окна. При срабатывании:

Инструменты MCP помечаются как defer_loading: true вместо загрузки в контекст заранее
Claude использует инструмент поиска для обнаружения релевантных инструментов MCP при необходимости
В контекст загружаются только инструменты, которые Claude действительно нужны

Поиск инструментов требует моделей, поддерживающих блоки tool_reference: Sonnet 4 и позже или Opus 4 и позже. Модели Haiku не поддерживают поиск инструментов.

Настройка поиска инструментов

Управляйте поведением поиска инструментов с помощью переменной окружения ENABLE_TOOL_SEARCH:

Значение	Поведение
`auto`	Активируется, когда инструменты MCP превышают 10% контекста (по умолчанию)
`auto:5`	Активируется при пороге 5% (настройте процент)
`true`	Всегда включено
`false`	Отключено, все инструменты MCP загружаются заранее

Установите значение в опции env:

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // Enable at 5% threshold
  }
};

Аутентификация

Большинство серверов MCP требуют аутентификации для доступа к внешним сервисам. Передавайте учётные данные через переменные окружения в конфигурации сервера.

Передача учётных данных через переменные окружения

Используйте поле env для передачи ключей API, токенов и других учётных данных на сервер MCP:

Полный рабочий пример с логированием отладки см. в разделе Список проблем из репозитория.

HTTP-заголовки для удалённых серверов

Для серверов HTTP и SSE передавайте заголовки аутентификации непосредственно в конфигурации сервера:

Аутентификация OAuth2

Спецификация MCP поддерживает OAuth 2.1 для авторизации. SDK не обрабатывает потоки OAuth автоматически, но вы можете передавать токены доступа через заголовки после завершения потока OAuth в вашем приложении:

// After completing OAuth flow in your app
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
  mcpServers: {
    "oauth-api": {
      type: "http",
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  },
  allowedTools: ["mcp__oauth-api__*"]
};

Примеры

Список проблем из репозитория

Этот пример подключается к серверу GitHub MCP для получения списка недавних проблем. Пример включает логирование отладки для проверки подключения MCP и вызовов инструментов.

Перед запуском создайте личный токен доступа GitHub с областью repo и установите его как переменную окружения:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the 3 most recent issues in anthropics/claude-code",
  options: {
    mcpServers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
})) {
  // Verify MCP server connected successfully
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }

  // Log when Claude calls an MCP tool
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
        console.log("MCP tool called:", block.name);
      }
    }
  }

  // Print the final result
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Запрос к базе данных

Этот пример использует сервер Postgres MCP для запроса к базе данных. Строка подключения передаётся как аргумент серверу. Агент автоматически обнаруживает схему базы данных, пишет SQL-запрос и возвращает результаты:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
  // Natural language query - Claude writes the SQL
  prompt: "How many users signed up last week? Break it down by day.",
  options: {
    mcpServers: {
      "postgres": {
        command: "npx",
        // Pass connection string as argument to the server
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // Allow only read queries, not writes
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Обработка ошибок

Серверы MCP могут не подключиться по различным причинам: процесс сервера может быть не установлен, учётные данные могут быть неверными или удалённый сервер может быть недоступен.

SDK отправляет сообщение system с подтипом init в начале каждого запроса. Это сообщение включает статус подключения для каждого сервера MCP. Проверьте поле status для обнаружения сбоев подключения перед началом работы агента:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

Устранение неполадок

Сервер показывает статус "failed"

Проверьте сообщение init, чтобы увидеть, какие серверы не подключились:

if (message.type === "system" && message.subtype === "init") {
  for (const server of message.mcp_servers) {
    if (server.status === "failed") {
      console.error(`Server ${server.name} failed to connect`);
    }
  }
}

Распространённые причины:

Отсутствующие переменные окружения: убедитесь, что установлены необходимые токены и учётные данные. Для серверов stdio проверьте, что поле env соответствует тому, что ожидает сервер.
Сервер не установлен: для команд npx убедитесь, что пакет существует и Node.js находится в вашем PATH.
Неверная строка подключения: для серверов баз данных проверьте формат строки подключения и доступность базы данных.
Проблемы с сетью: для удалённых серверов HTTP/SSE проверьте, что URL доступен и брандмауэры разрешают подключение.

Инструменты не вызываются

Если Claude видит инструменты, но не использует их, проверьте, что вы предоставили разрешение с помощью allowedTools или изменив режим разрешений:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Required for Claude to use the tools
}

Тайм-ауты подключения

SDK MCP имеет тайм-аут по умолчанию 60 секунд для подключений к серверам. Если ваш сервер запускается дольше, подключение не удастся. Для серверов, которым требуется больше времени на запуск, рассмотрите:

Использование более лёгкого сервера, если доступно
Предварительный прогрев сервера перед запуском вашего агента
Проверку логов сервера на предмет медленной инициализации

Связанные ресурсы

Руководство по пользовательским инструментам: создайте свой собственный сервер MCP, который работает в процессе с вашим приложением SDK
Разрешения: управляйте, какие инструменты MCP может использовать ваш агент, с помощью allowedTools и disallowedTools
Справочник TypeScript SDK: полный справочник API, включая параметры конфигурации MCP
Справочник Python SDK: полный справочник API, включая параметры конфигурации MCP
Каталог серверов MCP: просмотрите доступные серверы MCP для баз данных, API и многого другого

Was this page helpful?