На этой странице рассматривается конфигурация MCP для Agent SDK. Чтобы добавить MCP серверы в Claude Code CLI так, чтобы они загружались в каждом проекте, см. Области установки MCP.
Быстрый старт
Этот пример подключается к MCP серверу документации Claude Code с использованием HTTP транспорта и используетallowedTools с подстановочным знаком для разрешения всех инструментов с сервера.
Добавление MCP сервера
Вы можете настроить MCP серверы в коде при вызовеquery() или в файле .mcp.json, загруженном через settingSources.
В коде
Передайте MCP серверы непосредственно в опцииmcpServers:
Из файла конфигурации
Создайте файл.mcp.json в корне вашего проекта. Файл загружается, когда включен источник параметров project, что происходит по умолчанию для опций query(). Если вы явно установите settingSources, включите "project" для загрузки этого файла:
Разрешение MCP инструментов
MCP инструменты требуют явного разрешения перед тем, как Claude сможет их использовать. Без разрешения Claude увидит, что инструменты доступны, но не сможет их вызывать.Соглашение об именовании инструментов
MCP инструменты следуют шаблону именованияmcp__<server-name>__<tool-name>. Например, сервер GitHub с именем "github" с инструментом list_issues становится mcp__github__list_issues.
Предоставление доступа с помощью allowedTools
ИспользуйтеallowedTools для автоматического одобрения определённых MCP инструментов, чтобы Claude мог их использовать без запроса разрешения:
*) позволяют разрешить все инструменты с сервера без перечисления каждого отдельно.
Предпочитайте
allowedTools режимам разрешений для доступа MCP. permissionMode: "acceptEdits" не одобряет автоматически MCP инструменты (только редактирование файлов и команды Bash файловой системы). permissionMode: "bypassPermissions" одобряет автоматически MCP инструменты, но также отключает все остальные подсказки безопасности, что шире, чем необходимо. Подстановочный знак в allowedTools предоставляет доступ ровно к нужному MCP серверу и ничему больше. См. Режимы разрешений для полного сравнения.Обнаружение доступных инструментов
Чтобы увидеть, какие инструменты предоставляет MCP сервер, проверьте документацию сервера или подключитесь к серверу и проверьте сообщение инициализацииsystem:
Типы транспорта
MCP серверы взаимодействуют с вашим агентом, используя различные протоколы транспорта. Проверьте документацию сервера, чтобы увидеть, какой транспорт он поддерживает:- Если в документации указана команда для запуска (например,
npx @modelcontextprotocol/server-github), используйте stdio - Если в документации указан URL, используйте HTTP или SSE
- Если вы создаёте свои собственные инструменты в коде, используйте SDK MCP сервер
Серверы stdio
Локальные процессы, которые взаимодействуют через stdin/stdout. Используйте это для MCP серверов, которые вы запускаете на той же машине:- В коде
- .mcp.json
Серверы HTTP/SSE
Используйте HTTP или SSE для облачных MCP серверов и удалённых API:- В коде
- .mcp.json
"type": "http" вместо этого. В .mcp.json и других JSON файлах конфигурации "streamable-http" принимается как псевдоним для "http". Программный параметр mcpServers принимает только "http".
SDK MCP серверы
Определите пользовательские инструменты непосредственно в коде вашего приложения вместо запуска отдельного процесса сервера. Подробности реализации см. в руководстве по пользовательским инструментам.Поиск MCP инструментов
Когда у вас настроено много MCP инструментов, определения инструментов могут потребить значительную часть вашего контекстного окна. Поиск инструментов решает эту проблему, скрывая определения инструментов из контекста и загружая только те, которые Claude нужны для каждого хода. Поиск инструментов включен по умолчанию. Подробности конфигурации см. в Поиск инструментов. Для получения дополнительной информации, включая лучшие практики и использование поиска инструментов с пользовательскими SDK инструментами, см. руководство по поиску инструментов.Аутентификация
Большинство MCP серверов требуют аутентификации для доступа к внешним сервисам. Передавайте учётные данные через переменные окружения в конфигурации сервера.Передача учётных данных через переменные окружения
Используйте полеenv для передачи ключей API, токенов и других учётных данных на MCP сервер:
- В коде
- .mcp.json
HTTP заголовки для удалённых серверов
Для серверов HTTP и SSE передавайте заголовки аутентификации непосредственно в конфигурации сервера:- В коде
- .mcp.json
Аутентификация OAuth2
Спецификация MCP поддерживает OAuth 2.1 для авторизации. SDK не обрабатывает потоки OAuth автоматически, но вы можете передавать токены доступа через заголовки после завершения потока OAuth в вашем приложении:Примеры
Список проблем из репозитория
Этот пример подключается к GitHub MCP серверу для списка последних проблем. Пример включает логирование отладки для проверки подключения MCP и вызовов инструментов. Перед запуском создайте личный токен доступа GitHub с областьюrepo и установите его как переменную окружения:
Запрос к базе данных
Этот пример использует Postgres MCP сервер для запроса к базе данных. Строка подключения передаётся как аргумент серверу. Агент автоматически обнаруживает схему базы данных, пишет SQL запрос и возвращает результаты:Обработка ошибок
MCP серверы могут не подключиться по различным причинам: процесс сервера может быть не установлен, учётные данные могут быть неверными или удалённый сервер может быть недоступен. SDK отправляет сообщениеsystem с подтипом init в начале каждого запроса. Это сообщение включает статус подключения для каждого MCP сервера. Проверьте поле status для обнаружения сбоев подключения перед тем, как агент начнёт работать:
Troubleshooting
Сервер показывает статус “failed”
Проверьте сообщениеinit, чтобы увидеть, какие серверы не подключились:
- Отсутствующие переменные окружения: Убедитесь, что требуемые токены и учётные данные установлены. Для серверов stdio проверьте, что поле
envсоответствует тому, что ожидает сервер. - Сервер не установлен: Для команд
npxпроверьте, что пакет существует и Node.js находится в вашем PATH. - Неверная строка подключения: Для серверов баз данных проверьте формат строки подключения и что база данных доступна.
- Проблемы с сетью: Для удалённых серверов HTTP/SSE проверьте, что URL доступен и любые брандмауэры разрешают подключение.
Инструменты не вызываются
Если Claude видит инструменты, но не использует их, проверьте, что вы предоставили разрешение с помощьюallowedTools:
Тайм-ауты подключения
SDK MCP имеет тайм-аут по умолчанию 60 секунд для подключений сервера. Если ваш сервер требует больше времени для запуска, подключение не удастся. Для серверов, которым требуется больше времени на запуск, рассмотрите:- Использование более лёгкого сервера, если доступно
- Предварительный прогрев сервера перед запуском вашего агента
- Проверку логов сервера на предмет причин медленной инициализации
Связанные ресурсы
- Руководство по пользовательским инструментам: Создайте свой собственный MCP сервер, который работает в процессе с вашим приложением SDK
- Разрешения: Контролируйте, какие MCP инструменты может использовать ваш агент с помощью
allowedToolsиdisallowedTools - Справочник TypeScript SDK: Полный справочник API, включая опции конфигурации MCP
- Справочник Python SDK: Полный справочник API, включая опции конфигурации MCP
- Каталог MCP серверов: Просмотрите доступные MCP серверы для баз данных, API и многого другого