Перейти к основному содержанию
Model Context Protocol (MCP) — это открытый стандарт для подключения AI агентов к внешним инструментам и источникам данных. С помощью MCP ваш агент может запрашивать базы данных, интегрироваться с API, такими как Slack и GitHub, и подключаться к другим сервисам без написания пользовательских реализаций инструментов. MCP серверы могут работать как локальные процессы, подключаться через HTTP или выполняться непосредственно в вашем приложении SDK.
На этой странице рассматривается конфигурация MCP для Agent SDK. Чтобы добавить MCP серверы в Claude Code CLI так, чтобы они загружались в каждом проекте, см. Области установки MCP.

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

Этот пример подключается к 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);
  }
}
Агент подключается к серверу документации, ищет информацию о hooks и возвращает результаты.

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

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

В коде

Передайте 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 в корне вашего проекта. Файл загружается, когда включен источник параметров project, что происходит по умолчанию для опций query(). Если вы явно установите settingSources, включите "project" для загрузки этого файла:
{
  "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 мог их использовать без запроса разрешения:
const _ = {
  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
    ]
  }
};
Подстановочные знаки (*) позволяют разрешить все инструменты с сервера без перечисления каждого отдельно.
Предпочитайте allowedTools режимам разрешений для доступа MCP. permissionMode: "acceptEdits" не одобряет автоматически MCP инструменты (только редактирование файлов и команды Bash файловой системы). permissionMode: "bypassPermissions" одобряет автоматически MCP инструменты, но также отключает все остальные подсказки безопасности, что шире, чем необходимо. Подстановочный знак в allowedTools предоставляет доступ ровно к нужному MCP серверу и ничему больше. См. Режимы разрешений для полного сравнения.

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

Чтобы увидеть, какие инструменты предоставляет 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
  • Если вы создаёте свои собственные инструменты в коде, используйте SDK MCP сервер

Серверы stdio

Локальные процессы, которые взаимодействуют через stdin/stdout. Используйте это для MCP серверов, которые вы запускаете на той же машине:
const _ = {
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]
  }
};

Серверы HTTP/SSE

Используйте HTTP или SSE для облачных MCP серверов и удалённых API:
const _ = {
  options: {
    mcpServers: {
      "remote-api": {
        type: "sse",
        url: "https://api.example.com/mcp/sse",
        headers: {
          Authorization: `Bearer ${process.env.API_TOKEN}`
        }
      }
    },
    allowedTools: ["mcp__remote-api__*"]
  }
};
Для потокового HTTP транспорта используйте "type": "http" вместо этого. В .mcp.json и других JSON файлах конфигурации "streamable-http" принимается как псевдоним для "http". Программный параметр mcpServers принимает только "http".

SDK MCP серверы

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

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

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

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

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

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

Используйте поле env для передачи ключей API, токенов и других учётных данных на MCP сервер:
const _ = {
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
};
Полный рабочий пример с логированием отладки см. в разделе Список проблем из репозитория.

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

Для серверов HTTP и SSE передавайте заголовки аутентификации непосредственно в конфигурации сервера:
const _ = {
  options: {
    mcpServers: {
      "secure-api": {
        type: "http",
        url: "https://api.example.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.API_TOKEN}`
        }
      }
    },
    allowedTools: ["mcp__secure-api__*"]
  }
};

Аутентификация 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.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");
  }
}

Troubleshooting

Сервер показывает статус “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:
const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
  }
};

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

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

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