Подключение к внешним инструментам с помощью 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);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
options = ClaudeAgentOptions(
mcp_servers={
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp",
}
},
allowed_tools=["mcp__claude-code-docs__*"],
)
async for message in query(
prompt="Use the docs MCP server to explain what hooks are in Claude Code",
options=options,
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Агент подключается к серверу документации, ищет информацию о 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);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
options = ClaudeAgentOptions(
mcp_servers={
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/me/projects",
],
}
},
allowed_tools=["mcp__filesystem__*"],
)
async for message in query(prompt="List files in my project", options=options):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Из файла конфигурации
Создайте файл .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
]
}
};
Подстановочные знаки (*) позволяют разрешить все инструменты с сервера без перечисления каждого отдельно.
Обнаружение доступных инструментов
Чтобы увидеть, какие инструменты предоставляет 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"]
}
};
options = ClaudeAgentOptions(
mcp_servers={
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
}
},
allowed_tools=["mcp__github__list_issues", "mcp__github__search_issues"],
)
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
Серверы 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__*"]
}
};
options = ClaudeAgentOptions(
mcp_servers={
"remote-api": {
"type": "sse",
"url": "https://api.example.com/mcp/sse",
"headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},
}
},
allowed_tools=["mcp__remote-api__*"],
)
{
"mcpServers": {
"remote-api": {
"type": "sse",
"url": "https://api.example.com/mcp/sse",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}
Для потокового 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"]
}
};
options = ClaudeAgentOptions(
mcp_servers={
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
}
},
allowed_tools=["mcp__github__list_issues"],
)
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
Синтаксис ${GITHUB_TOKEN} расширяет переменные окружения во время выполнения.
Полный рабочий пример с логированием отладки см. в разделе Список проблем из репозитория.
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__*"]
}
};
options = ClaudeAgentOptions(
mcp_servers={
"secure-api": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {"Authorization": f"Bearer {os.environ['API_TOKEN']}"},
}
},
allowed_tools=["mcp__secure-api__*"],
)
{
"mcpServers": {
"secure-api": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}
Синтаксис ${API_TOKEN} расширяет переменные окружения во время выполнения.
Аутентификация 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__*"]
};
# After completing OAuth flow in your app
access_token = await get_access_token_from_oauth_flow()
options = ClaudeAgentOptions(
mcp_servers={
"oauth-api": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {"Authorization": f"Bearer {access_token}"},
}
},
allowed_tools=["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);
}
}
import asyncio
import os
from claude_agent_sdk import (
query,
ClaudeAgentOptions,
ResultMessage,
SystemMessage,
AssistantMessage,
)
async def main():
options = ClaudeAgentOptions(
mcp_servers={
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
}
},
allowed_tools=["mcp__github__list_issues"],
)
async for message in query(
prompt="List the 3 most recent issues in anthropics/claude-code",
options=options,
):
# Verify MCP server connected successfully
if isinstance(message, SystemMessage) and message.subtype == "init":
print("MCP servers:", message.data.get("mcp_servers"))
# Log when Claude calls an MCP tool
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "name") and block.name.startswith("mcp__"):
print("MCP tool called:", block.name)
# Print the final result
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Запрос к базе данных
Этот пример использует 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);
}
}
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
# Connection string from environment variable
connection_string = os.environ["DATABASE_URL"]
options = ClaudeAgentOptions(
mcp_servers={
"postgres": {
"command": "npx",
# Pass connection string as argument to the server
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
connection_string,
],
}
},
# Allow only read queries, not writes
allowed_tools=["mcp__postgres__query"],
)
# Natural language query - Claude writes the SQL
async for message in query(
prompt="How many users signed up last week? Break it down by day.",
options=options,
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Обработка ошибок
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");
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
async def main():
options = ClaudeAgentOptions(mcp_servers={"data-processor": data_server})
async for message in query(prompt="Process data", options=options):
if isinstance(message, SystemMessage) and message.subtype == "init":
failed_servers = [
s
for s in message.data.get("mcp_servers", [])
if s.get("status") != "connected"
]
if failed_servers:
print(f"Failed to connect: {failed_servers}")
if (
isinstance(message, ResultMessage)
and message.subtype == "error_during_execution"
):
print("Execution failed")
asyncio.run(main())
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 секунд для подключений сервера. Если ваш сервер требует больше времени для запуска, подключение не удастся. Для серверов, которым требуется больше времени на запуск, рассмотрите:
- Использование более лёгкого сервера, если доступно
- Предварительный прогрев сервера перед запуском вашего агента
- Проверку логов сервера на предмет причин медленной инициализации
Связанные ресурсы
- Руководство по пользовательским инструментам: Создайте свой собственный MCP сервер, который работает в процессе с вашим приложением SDK
- Разрешения: Контролируйте, какие MCP инструменты может использовать ваш агент с помощью
allowedToolsиdisallowedTools - Справочник TypeScript SDK: Полный справочник API, включая опции конфигурации MCP
- Справочник Python SDK: Полный справочник API, включая опции конфигурации MCP
- Каталог MCP серверов: Просмотрите доступные MCP серверы для баз данных, API и многого другого