SpyBara
Go Premium

agent-sdk/mcp.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 266 additions and 176 deletions.

2026
Thu 10 23:00 Mon 14 22:58 Fri 18 23:58

Подключение к внешним инструментам с помощью 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);
}
}

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

Добавить MCP сервер

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

В коде

Передайте MCP серверы непосредственно в опции mcpServers. Этот пример запускает локальный файловый MCP сервер для /Users/me/projects. Замените этот путь на директорию на вашей машине:

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" для загрузки этого файла. Замените /Users/me/projects на директорию на вашей машине:

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

Время подключения

Claude Code регистрирует серверы, которые вы передаёте в options.mcpServers при запуске и отправляет сообщение инициализации после разрешения первого ожидания, если оно есть. Без options.mcpServers Claude Code ждёт 2 секунды для ожидающих серверов перед первым ходом, поэтому серверы, загруженные из файлов конфигурации, таких как .mcp.json, обычно показывают статус pending при инициализации. Когда каждый сервер из options.mcpServers подключается и задерживает ли он первый ход, зависит от его типа:

Тип сервера Задерживает первый ход? Тайм-аут ожидания первого хода
Сервер stdio или HTTP/SSE сервер без кэшированного списка инструментов Да, до подключения MCP_TIMEOUT, по умолчанию 30 секунд; подключение завершается ошибкой в этот момент
Удалённый сервер с кэшированным списком инструментов, сохранённый Claude Code из предыдущего подключения Нет; кэшированные инструменты доступны с первого хода Нет; подключается при первом вызове инструмента, и это отложенное подключение имеет собственный тайм-аут
In-process SDK сервер Нет; никогда не задерживает первый ход Нет

Чтобы заблокировать сам запуск на отдельной, более ранней фазе, чем ожидание первого хода, перед отправкой сообщения инициализации:

  • Установите MCP_CONNECTION_NONBLOCKING в значение 0, чтобы заблокировать всю партию подключений. Claude Code ограничивает это ожидание 5 секундами по умолчанию. Отрегулируйте ограничение с помощью переменной окружения MCP_CONNECT_TIMEOUT_MS в миллисекундах. Серверы, которые всё ещё ожидают в этот момент, продолжают подключаться в фоновом режиме.
  • Установите alwaysLoad: true в конфигурации сервера, чтобы его инструменты были доступны с полными схемами на первом ходе, исключены из отложенного поиска инструментов. Claude Code ждёт при запуске инструментов этого сервера, ограничено тем же сроком, в то время как другие серверы продолжают подключаться в фоновом режиме; удалённый сервер с кэшированным списком инструментов предоставляет их без подключения, согласно таблице выше.

Сообщение system с подтипом init сообщает статус каждого сервера в момент его отправки; см. Обработка ошибок для чтения этих статусов.

Разрешить инструменты 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
]
}
};

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

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

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

Claude Code выдаёт инициализирующее сообщение после ожидания подключения на первом ходу для серверов, переданных в options.mcpServers, поэтому массив tools содержит инструменты mcp__ каждого сервера, который подключился к этому моменту, плюс те, у которых есть кэшированный список инструментов, которые подключаются при первом использовании. Инструменты любого другого сервера, который ещё не подключился, отсутствуют; см. Обработка ошибок для чтения статуса каждого сервера.

Этот фильтр выводит имена инструментов MCP:

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

const options = {
mcpServers: {
// your servers
},
};

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

Вы также можете попросить Claude перечислить инструменты, доступные с сервера.

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

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

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

stdio серверы

Локальные процессы, которые взаимодействуют через stdin/stdout. Используйте это для MCP серверов, которые вы запускаете на одной машине. Для формата .mcp.json используйте те же поля, показанные в From a config file. В коде передайте команду и её аргументы. Замените /Users/me/projects на директорию на вашей машине:

const _ = {
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__read_file", "mcp__filesystem__list_directory"]
}
};

HTTP/SSE серверы

Используйте HTTP или SSE для облачных MCP серверов и удалённых API. Для формата .mcp.json используйте те же поля, что и в примере в HTTP headers for remote servers, с "type": "sse" для SSE сервера. В коде передайте URL сервера:

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". Тип McpHttpServerConfig в SDK объявляет только "http", поэтому используйте "http" для серверов, которые вы передаёте в коде.

SDK MCP серверы

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

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

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

Поиск инструментов включен по умолчанию. Дополнительную информацию о параметрах конфигурации, лучших практиках и использовании поиска инструментов с пользовательскими инструментами SDK см. в разделе Поиск инструментов.

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

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

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

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

const _ = {
options: {
mcpServers: {
"api-server": {
command: "npx",
args: ["-y", "@your-org/api-mcp-server"],
env: {
API_KEY: process.env.API_KEY
}
}
},
allowedTools: ["mcp__api-server__*"]
}
};

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. Когда настроенный сервер возвращает запрос авторизации и нет сохраненного токена, запуск агента продолжается без инструментов этого сервера, и сервер сообщает статус needs-auth. Массив mcp_servers системного инициализирующего сообщения может по-прежнему показывать pending для этого сервера при его отправке. Чтобы подтвердить, требуются ли серверу учетные данные, опросите mcpServerStatus() в TypeScript SDK или get_mcp_status() в Python.

Для предоставления учетных данных завершите поток OAuth в своем приложении и передайте полученный токен доступа в headers сервера:

// После завершения потока OAuth в вашем приложении.
// Реализуйте getAccessTokenFromOAuthFlow для вашего поставщика OAuth.
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 с правами на чтение репозиториев, которые вы хотите запросить, и установите его как переменную окружения:

export GITHUB_TOKEN=YOUR_GITHUB_PAT

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: {
type: "http",
url: "https://api.githubcopilot.com/mcp/",
headers: {
Authorization: `Bearer ${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);
}
}

В строке MCP servers: статус connected для github подтверждает, что токен работает. Если Claude Code имеет кэшированный список инструментов для сервера, статус может отображаться как pending, и сервер подключится при первом вызове инструмента. Если статус failed или needs-auth, см. Обработка ошибок перед тем, как доверять результату, так как Claude может вернуться к встроенным инструментам, когда сервер недоступен.

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

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

Инструмент execute_sql DBHub выполняет любой SQL, который выдаёт агент, включая операции записи, если вы это не ограничите. Установка readonly = true в файле конфигурации DBHub заставляет DBHub отклонять операторы INSERT, UPDATE, DELETE и DDL, поэтому пример не может изменять ваши данные, даже если агент выдаст операцию записи. DBHub разрешает ${DATABASE_URL} из переменных окружения процесса при загрузке конфига, поэтому строка подключения остаётся вне файла. Создайте этот файл dbhub.toml рядом с вашим скриптом:

[[sources]]
id = "production"
dsn = "${DATABASE_URL}"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true

Затем скрипт указывает DBHub на файл конфигурации вместо прямой передачи строки подключения. Перед запуском установите переменную окружения DATABASE_URL на вашу строку подключения. Замените значения-заполнители на детали вашей базы данных:

export DATABASE_URL=postgresql://user:password@localhost:5432/mydb

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

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",
// dbhub.toml sets readonly = true, so execute_sql rejects writes
args: ["-y", "@bytebase/dbhub", "--config", "dbhub.toml"]
}
},
allowedTools: ["mcp__postgres__execute_sql"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

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

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

Claude Code отправляет сообщение system с подтипом init в начале каждого запроса. Это сообщение включает статус подключения для каждого MCP сервера. Поле status может быть "pending", "connected", "failed", "needs-auth" или "disabled". Claude Code отправляет сообщение init после первого ожидания подключения для серверов, переданных в options.mcpServers, поэтому такой сервер, который подключился в течение ожидания, показывает "connected".

В сообщении init не рассматривайте "pending" как ошибку само по себе. Это может означать любое из следующего:

Проверьте "failed" или "needs-auth" для обнаружения серверов, которые не будут пригодны для использования:

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

try {
for await (const message of query({
prompt: "Process data",
options: {
mcpServers: {
// Replace dataServer with your server configuration
"data-processor": dataServer
}
}
})) {
if (message.type === "system" && message.subtype === "init") {
const unavailableServers = message.mcp_servers.filter(
(s) => s.status === "failed" || s.status === "needs-auth"
);

if (unavailableServers.length > 0) {
console.warn("Unavailable MCP servers:", unavailableServers);
}
}

if (message.type === "result" && message.subtype === "error_during_execution") {
console.error("Execution failed");
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branch above has
// already run; a failure to start or reach the Claude Code process
// yields no result message. MCP servers that fail to connect don't
// throw: use the status check above, and note that servers still
// "pending" at init need a later status check.
console.log(`Session ended with an error: ${error}`);
}

Статус удаленного сервера также может измениться после того, как он сообщит "connected". Когда соединение с ним разрывается во время сеанса, Claude Code переводит сервер обратно в "pending" во время переподключения. Последующий вызов mcpServerStatus() в TypeScript или ClaudeSDKClient.get_mcp_status() в Python может затем сообщить "pending" для сервера, который вы видели подключенным ранее, без каких-либо изменений конфигурации с вашей стороны.

После пяти неудачных попыток переподключения сервер сообщает "failed" или "needs-auth", когда ему требуется повторная авторизация. Для повторной попытки вручную вызовите reconnectMcpServer() в TypeScript или ClaudeSDKClient.reconnect_mcp_server() в Python.

Troubleshooting

Server shows "failed" status

Check the init message to see which servers failed to connect:

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`);
}
}
}

A "pending" status doesn't mean the server failed. See Обработка ошибок for the cases it covers at init. To get updated statuses later in the session, call the query's mcpServerStatus() method in the TypeScript SDK, or ClaudeSDKClient.get_mcp_status() in Python.

Common causes:

  • Missing environment variables: Ensure required tokens and credentials are set. For stdio servers, check the env field matches what the server expects.
  • Server not installed: For npx commands, verify the package exists and Node.js is in your PATH.
  • Invalid connection string: For database servers, verify the connection string format and that the database is accessible.
  • Network issues: For remote HTTP/SSE servers, check the URL is reachable and any firewalls allow the connection.

Tools not being called

If Claude sees tools but doesn't use them, check that you've granted permission with allowedTools:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
}
};

Connection timeouts

MCP server connections time out after 30 seconds by default. To change how long a running tool call may take, set MCP_TOOL_TIMEOUT. If your server takes longer to start, the connection fails. Raise the connection limit with the MCP_TIMEOUT environment variable, in milliseconds. For servers that need more startup time, also consider:

  • Using a lighter-weight server if available
  • Pre-warming the server before starting your agent
  • Checking server logs for slow initialization causes

In TypeScript, you can set the tool-call limit for a single SDK MCP server by passing timeout to createSdkMcpServer().

Tool output exceeds maximum allowed tokens

The SDK applies the same MCP output limit as Claude Code. When a tool result with no image content is larger than 25,000 tokens, Claude Code saves the output to a file and replaces the tool result with an error message that names the file path, so the agent can read the output back in portions.

Raise the limit with the MAX_MCP_OUTPUT_TOKENS environment variable. See MCP output limits and warnings for the full behavior, including how a server can declare a higher per-tool limit with the anthropic/maxResultSizeChars annotation.