MCP: подключаем внешние инструменты

Из коробки Codex умеет читать и править файлы, запускать команды и искать в интернете. Всё остальное — задача в трекере, макет, документация библиотеки нужной версии, данные из CRM — ему приходится пересказывать в чате. Model Context Protocol (MCP) убирает эту ручную работу: вы подключаете сервер, и у агента появляются новые инструменты. В этом уроке — механика подключения; конкретные серверы для браузера, GitLab, базы и документации разбираются в следующем уроке.

Что такое MCP

MCP — открытый протокол, по которому агент (клиент) общается с сервером, предоставляющим инструменты. Сервер описывает, какие инструменты у него есть и какие параметры они принимают, а затем выполняет вызовы — например, «найти задачу по номеру» или «получить документацию по пакету». Codex выступает клиентом: при старте он подключается к настроенным серверам, получает список инструментов и даёт модели ими пользоваться наравне со встроенными.

Сервер может вернуть при подключении поле instructions — общие указания по работе с ним. Codex их читает и использует, причём особенно важны первые 512 символов: если вы пишете свой сервер, держите главное там.

Если вы проходили курс «Введение в MCP», протокол вам знаком: серверы те же самые, отличается только конфигурация клиента.

Два транспорта

STDIO-сервер запускается на вашей машине и живёт, пока работает сессия. HTTP-сервер работает сам по себе, а Codex к нему подключается.

Подключение из командной строки

STDIO-сервер — команда после --:

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add crm-sandbox --env CRM_BASE_URL=https://sandbox.crm.example -- node ./tools/crm-mcp/index.js

HTTP-сервер — флаг --url:

codex mcp add figma --url https://mcp.figma.com/mcp
codex mcp add internal-docs --url https://mcp.docs.company.internal/mcp --bearer-token-env-var DOCS_MCP_TOKEN

Управление:

codex mcp list              # все серверы, --json для скриптов
codex mcp get figma         # конфигурация одного сервера
codex mcp login figma       # OAuth-вход, --scopes a,b — запросить области доступа
codex mcp logout figma
codex mcp remove figma

codex mcp add записывает сервер в ~/.codex/config.toml. В TUI команда /mcp показывает активные серверы, /mcp verbose — подробности. Конфигурация MCP общая у CLI, IDE-расширения и десктопного приложения: настроили в одном месте — работает везде.

Подключение через config.toml

Для тонкой настройки удобнее править файл. Каждый сервер — таблица [mcp_servers.<имя>].

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 20

[mcp_servers.crm-sandbox]
command = "node"
args = ["./tools/crm-mcp/index.js"]
cwd = "/Users/me/work/site"
env = { CRM_BASE_URL = "https://sandbox.crm.example" }
env_vars = ["CRM_API_TOKEN"]          # пробросить переменную из вашего окружения

[mcp_servers.internal-docs]
url = "https://mcp.docs.company.internal/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
http_headers = { "X-Team" = "web" }
tool_timeout_sec = 30

Ключи STDIO-сервера: command (обязательный), args, env — заданные значения, env_vars — какие переменные взять из вашего окружения, cwd. Ключи HTTP-сервера: url (обязательный), bearer_token_env_var, http_headers — статичные заголовки, env_http_headers — заголовки из переменных окружения, auth. Общие: startup_timeout_sec (по умолчанию 10), tool_timeout_sec (по умолчанию 60), enabled = false — выключить, не удаляя, required = true — не стартовать, если сервер не поднялся.

Сервер, нужный всей команде для конкретного проекта, можно описать в проектном .codex/config.toml — он работает в доверенных проектах. Секреты туда не пишите: в репозиторий попадает только имя переменной (env_vars, bearer_token_env_var), а значение каждый держит у себя.

OAuth

Многие облачные MCP-серверы используют OAuth. Обычно достаточно codex mcp login <имя>: Codex откроет браузер, вы войдёте, токен сохранится. Codex поддерживает автоматическую регистрацию клиента (CIMD и Dynamic Client Registration), поэтому чаще всего ничего настраивать не нужно.

Если сервер требует заранее зарегистрированного клиента, передайте его идентификатор при добавлении:

codex mcp add tracker --url https://mcp.tracker.example/mcp --oauth-client-id codex-web-team

Codex покажет адрес обратного вызова, который нужно зарегистрировать у провайдера. Для конфиденциального клиента есть --oauth-client-secret, но секрет сохранится в config.toml — держите такой файл вне репозитория. На машине без браузера поможет codex mcp login <имя> --no-browser, а фиксированный порт обратного вызова задаётся ключом mcp_oauth_callback_port.

Какие инструменты и с какими одобрениями

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

[mcp_servers.tracker]
url = "https://mcp.tracker.example/mcp"
enabled_tools = ["get_issue", "search_issues", "add_comment"]
default_tools_approval_mode = "writes"

[mcp_servers.tracker.tools.add_comment]
approval_mode = "prompt"

• enabled_tools — список разрешённых инструментов, disabled_tools — запрещённых (применяется после enabled_tools).
• default_tools_approval_mode — как одобрять вызовы инструментов сервера. Значения: auto, prompt, writes, approve. prompt спрашивает каждый раз, writes спрашивает про инструменты, не помеченные сервером как только читающие. Точное поведение остальных значений сверяйте со справочником.
• tools.<инструмент>.approval_mode — исключение для одного инструмента, tools.<инструмент>.output_token_limit — ограничить объём его ответа.

Инструменты, которые сервер помечает как разрушительные (destructive), Codex выполняет только после одобрения — если только тот же инструмент не помечен как только читающий: эта пометка важнее. Поэтому пометки сервера — подсказка, а не гарантия: для чужих серверов задавайте approval_mode явно.

Безопасность и контекст

Три вещи, которые важно держать в голове.

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

Ответы серверов — непроверенные данные. Текст задачи из трекера или страница документации могут содержать инструкции, которые агент примет за ваши (prompt injection). Это повод держать одобрения для пишущих инструментов включёнными.

Каждый сервер стоит контекста. Описания инструментов и инструкции серверов занимают место в окне и расходуют лимит. Включайте серверы под задачу (enabled = false для остальных или -c mcp_servers.имя.enabled=false на один запуск) и сокращайте список инструментов. Документация советует начинать с одного-двух серверов, которые снимают реальную ручную работу.

Если вы читали старые инструкции

Команда codex mcp-server, которая запускала сам Codex как MCP-сервер для других агентов, удалена. Её заменяет App Server со своим протоколом JSON-RPC — это не MCP и не прямая замена (подробнее в курсе «Codex в автоматизации»). Подключать внешние MCP-серверы к Codex можно, как и раньше. Плагины тоже могут приносить MCP-серверы — о них в уроке про плагины.