MCP в Codex CLI и OpenCode: как подключить сервер

Чтобы подключить MCP-сервер к Codex CLI, добавьте таблицу [mcp_servers.<имя>] в файл ~/.codex/config.toml. В OpenCode то же самое делается в opencode.json — там сервера описываются объектами внутри блока mcp. Формат конфигов разный: TOML против JSON, поэтому готовый сниппет из документации одного агента во второй не переносится копированием.

Model Context Protocol — это способ дать агенту инструменты, которых у него нет из коробки: доступ к файловой системе вне проекта, к базе данных, к трекеру задач, к браузеру. Агент видит такой сервер как набор функций, которые он может вызвать во время работы над задачей. Дальше — конкретные конфиги для обоих агентов, проверка подключения и разбор мест, где легко ошибиться.

Как подключить MCP-сервер в Codex CLI

Codex CLI хранит настройки в ~/.codex/config.toml. Если файла нет, создайте его — агент подхватит конфиг при следующем запуске. Каждый MCP-сервер описывается отдельной таблицей вида [mcp_servers.<имя>], где имя вы придумываете сами: по нему сервер будет виден в списке подключённых.

Самый частый случай — локальный сервер, который агент запускает как дочерний процесс:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

Здесь command — исполняемый файл, args — массив аргументов к нему. Codex запустит npx -y @modelcontextprotocol/server-filesystem /home/user/projects и будет общаться с процессом по стандартному вводу-выводу. Последний аргумент в этом примере — директория, к которой сервер откроет доступ: серверы файловой системы обычно требуют явно указать разрешённый путь, чтобы агент не гулял по всему диску.

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

[mcp_servers.tasks]
command = "npx"
args = ["-y", "имя-пакета-mcp-сервера"]
env = { API_TOKEN = "${API_TOKEN}" }

Поле env в TOML — это inline-таблица, пары пишутся в фигурных скобках через запятую. Имя пакета подставьте из документации того сервера, который подключаете. Сам токен при этом лежит в окружении оболочки, а не в файле, который легко случайно закоммитить. Если вы не уверены, как экспортировать значение для текущей сессии, у нас есть разбор переменных окружения в bash и отдельная страница про команду export.

Codex читает конфиг ещё и на уровне проекта — из .codex/config.toml в корне репозитория. Но такой конфиг загружается только для директорий, которым вы выдали доверие: при первом запуске в новой папке агент спрашивает разрешение. Если проектные настройки будто игнорируются, первым делом проверьте, что директория помечена как доверенная.

Codex CLI должен быть установлен и авторизован до того, как вы возьмётесь за MCP — если этот шаг ещё впереди, посмотрите нашу инструкцию: Codex в России: как установить и настроить без VPN.

Codex и удалённые MCP-серверы

Не каждый сервер нужно запускать у себя. Часть из них живёт по HTTP, и тогда вместо command указывается адрес:

[mcp_servers.tracker]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TRACKER_TOKEN"

Ключевой момент — bearer_token_env_var. Здесь указывается не сам токен, а имя переменной окружения, из которой Codex его возьмёт. Значение в конфиг не попадает, и файл можно спокойно держать в дотфайлах.

Команда codex mcp add вместо ручного редактирования

Править TOML руками не обязательно. У Codex есть подкоманда, которая добавляет сервер в конфиг за вас:

codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

Двойной дефис отделяет имя сервера от команды, которой он запускается: всё, что идёт после --, попадёт в command и args. Набор доступных флагов у подкоманды меняется от версии к версии, так что перед первым использованием стоит заглянуть в codex mcp add --help.

Проверить, что получилось, можно так:

codex mcp list

Команда покажет серверы, о которых Codex знает. Если только что добавленного в списке нет — конфиг не прочитан: обычно это опечатка в названии таблицы (mcp_server вместо mcp_servers) или файл, лежащий не в ~/.codex/.

Как подключить MCP-сервер в OpenCode

OpenCode настраивается через opencode.json. Файл можно положить в корень проекта — тогда настройки действуют для этого репозитория. MCP-серверы описываются внутри блока mcp, где ключ объекта — это имя сервера:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "enabled": true
    }
  }
}

Разница с Codex видна сразу: command здесь не строка, а массив, в который входит и сам исполняемый файл, и все аргументы. Поле type обязательное — для локального процесса это "local". Флаг enabled позволяет временно отключить сервер, не удаляя его описание: поставили false, и агент перестал его запускать. Это удобно, когда сервер тяжело стартует и нужен не в каждой сессии.

Строка $schema не влияет на поведение агента, но даёт редактору подсказки по структуре файла — с ней опечатку в имени поля видно ещё до запуска.

Установка и первичная настройка OpenCode разобраны отдельно: OpenCode в России: установка и настройка без VPN.

Удалённый MCP-сервер в OpenCode

Для сервера, работающего по HTTP, меняется тип и вместо команды указывается адрес:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true
    }
  }
}

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

Codex TOML и OpenCode JSON: в чём разница

Оба агента решают одну задачу, но описывают её по-разному. Это главная причина, по которой конфиг не переносится между ними копированием.

Практический вывод: в Codex тип сервера выводится из того, что вы написали — есть command, значит локальный, есть url, значит удалённый. В OpenCode тип указывается явно, и забытое поле type — типичная причина, по которой сервер не поднимается.

Как проверить, что MCP-сервер подключился

В Codex CLI для этого есть codex mcp list — он перечислит серверы из конфига. Команда отвечает на вопрос «агент прочитал мои настройки?», и этого достаточно, чтобы отделить проблему с конфигом от проблемы с самим сервером.

В OpenCode отдельной команды для списка серверов ждать не стоит — проще перезапустить сессию и попросить агента перечислить доступные ему инструменты. Если инструменты сервера появились в ответе, подключение работает.

Что проверять, когда сервер не виден:

• Конфиг не там. Codex ищет config.toml в ~/.codex/, OpenCode — opencode.json в проекте. Файл в соседней директории агент не найдёт.
• Сервер не запускается сам по себе. Выполните команду из конфига руками в терминале. Если npx не может скачать пакет или падает с ошибкой — дело не в агенте.
• Не хватает переменной окружения. Сервер стартует, но сразу завершается — обычно это отсутствующий токен. Проверьте, что переменная действительно экспортирована в той оболочке, из которой вы запускаете агента.
• Сессия не перезапущена. Конфиг читается при старте. Агент, запущенный до правки файла, о новом сервере не узнает.
• Синтаксис. В TOML легко промахнуться с кавычками в inline-таблице, в JSON — оставить висящую запятую. И то, и другое ломает чтение всего файла, а не одной строки.

Что дальше

MCP закрывает вопрос «какие инструменты есть у агента», но не вопрос «какая модель за ним стоит». Рядом стоит второй файл, который стоит завести в репозитории, — AGENTS.md с правилами проекта: как собирать, чем тестировать, каких соглашений держаться. Как его писать, разобрано здесь: AGENTS.md: как написать инструкции для Codex и OpenCode.

И Codex CLI, и OpenCode бесполезны без доступа к модели — а из России это отдельная задача с оплатой и блокировками. Если не хотите разбираться с зарубежными картами и VPN, посмотрите AI для кода от PurpleSchool: один API-ключ с оплатой в рублях, который подключается к обоим агентам через переменные окружения.