mcp-agents

MCP-сервер, который оборачивает AI CLI-инструменты — Claude Code, Antigravity CLI (agy) и Codex CLI — и может проксировать Chrome DevTools MCP к удалённо арендованному браузеру.

Необходимые условия

• Node.js >= 26

• Как минимум один из следующих CLI должен быть установлен и доступен в $PATH:

Нужен только тот CLI, который вы выбираете с помощью --provider.

Related MCP server: claudecode-mcp

Установка

npm install -g mcp-agents

Глобальная установка — самый быстрый и надёжный способ запуска. npx -y mcp-agents после запуска MCP-сервера функционально эквивалентен, но до того момента, как MCP-клиент сможет подключиться, запуск зависит от состояния разрешения пакета и кэша npm.

Совет: Если в .mcp.json вашего проекта используется mcp-agents, добавьте npm install -g mcp-agents в ваш скрипт установки (например, bin/setup), чтобы новые разработчики получали его автоматически.

Быстрая проверка

# Default provider (codex)
mcp-agents

# Specific provider
mcp-agents --provider claude
mcp-agents --provider gemini

# Browser provider (example injected lease helper)
mcp-agents --provider browser \
  --browser_lease_command '["bin/box","--browser"]'

Сервер работает по JSON-RPC через stdio. Когда сервер начинает прослушивание, он выводит [mcp-agents] ready (provider: <name>) в stderr.

Провайдеры и инструменты

Каждый флаг --provider выбирает один CLI-бэкенд:

Проверки Claude

Для полноценной независимой оценки и ревью кода используйте фоновые инструменты:

1. Вызовите claude-start с полным промптом для ревью и абсолютным путём cwd.

2. Вызовите claude-status с возвращёнными jobId и cursor. Повторяйте с каждым новым cursor, пока состояние не станет терминальным.

3. Когда состояние станет completed, вызовите claude-result. Продолжайте с nextOffset, пока done не станет true.

4. Вызовите claude-cancel, если заключение больше не нужно.

claude-status по умолчанию использует long-polling по 10 секунд и принимает wait_ms до 60 секунд. Отмена ожидания статуса не отменяет саму задачу. Задачи одноразовые и действуют только в пределах текущего MCP-подключения: сессий ответов нет, а разрыв соединения отменяет активную работу. Сервер допускает 8 активных и 32 сохранённых задания, хранит завершённые задания в течение часа, выводит результаты страницами по 32 768 кодовых точек Unicode и отклоняет итоговый результат размером более 10 МиБ.

Фоновые проверки имеют двухчасовой дедлайн, установленный обёрткой. Операторы могут заменить его параметром --timeout <seconds> при запуске сервера; вызывающая сторона не может сократить время задания через timeout_ms. Claude зафиксирован на claude-opus-4-8 с усилием xhigh и работает как изолированный ревьюер: он сохраняет проектные инструкции и контекст репозитория, но отключает хуки, субагентов, навыки, слэш-команды, внешние MCP-серверы и инструменты внесения изменений. Доступны только Read, Glob, Grep и режим инспекции через Bash, доступный только в plan mode и только для чтения. Инструкция для листового ревьюера также запрещает выполнение тестов, установки, делегирование и внешние побочные эффекты. Промежуточные выходы модели, входы и результаты инструментов, а также рассуждения не передаются через MCP; наружу передаются только очищенный статус фаз и итоговый вердикт.

Используйте блокирующий инструмент claude_code только для небольших промптов, которые укладываются в тайм-аут клиента одним MCP-вызовом.

Параметры claude_code

Любые другие аргументы tools/call игнорируются (например, model, effort или config).

Claude зафиксирован на claude-opus-4-8 с усилием xhigh; вызывающий не может менять модель или усилие для отдельного вызова. Вызовы выполняются с --output-format json; сервер разбирает JSON и возвращает текст result ассистента (или ошибку MCP, если is_error=true). Более длинное значение по умолчанию рассчитано на глубокие ревью Opus; вызывающие силы могут указать меньший timeout_ms, а операторы сервера могут переопределить значение по умолчанию через --timeout <seconds>.

Параметры gemini

Любые дополнительные аргументы tools/call игнорируются (например, model или model_reasoning_effort).

agy всегда запускается с --sandbox (ограничения терминала включены); переключателя песочницы для отдельного вызова нет.

browser (прозрачный режим для удалённого Chrome)

Провайдер browser сразу запускает локальный сервер chrome-devtools-mcp, а затем при первом обращении к рекламируемому браузерному инструменту «лениво» получает аренду удалённого Chrome. MCP-сервер и все файлы, которые он создаёт, остаются локальными; через предоставленный оператором loopback-туннель передаётся только CDP. Вызовы, поступившие во время получения аренды, разделяют одну попытку подготовки и остаются в FIFO-порядке. Отдельных инструментов обёртки для acquire, status, release, job или отмены нет.

Быстрая настройка с crabbox

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

Ваш вспомогательный скрипт acquire делает четыре вещи: арендует бокс; запускает на нём Chromium с --remote-debugging-port=<remote>; открывает ssh -L 127.0.0.1:<local-cdp-port>:127.0.0.1:<remote> (добавьте соответствующий -R для --app-port, когда тестируемая страница раздаётся с вашей машины); затем, как только /json/version начнёт отвечать на локальном порту, выводит:

record_version=1
state=ready
generation=<opaque token>
local_cdp_port=<the port you were given>
browser_url=http://127.0.0.1:<that same port>

status перепроверяет эту аренду, release завершает её, а любой код возврата 69 сохраняет линию резервирования в состоянии fail-closed.

Провайдер не знает ни облака, ни на SSHQ. Внедрённая команда владеет арендой и получает следующие формы argv:

acquire --session <id> --local-cdp-port <port> --viewport <WxH> [--app-port <port>]
status --session <id> [--generation <token>]
release --session <id> --generation <token> --reason idle|shutdown

Успешный вывод acquire — это инертны и данные UTF-8 в формате key=value, содержащие запись готовности версии 1, поколение, выбранный локальный CDP-порт и соответствующий URL браузера. Код возврата 69 соответствует принципу fail-closed: вызов возвращает «GUI not verified — no browser box available» и никогда не запускает локальный браузер. Ошибка предварительной проверки локального dev-сервера, переданная хелпером, сохраняется дословно. Код 75 сообщает о гонке за привязку loopback; mcp-agents выбирает новый порт, перезапускает downstream, заново отправляет те же первоначальные возможности MCP initialize (включая roots и уведомление initialized) и повторяет попытку не более трёх раз, не отдавая наружу дубликат результата initialize.

chrome-devtools-mcp намеренно не зафиксирован — fallback плавает до последнего релиза. Никакая логика здесь не зависит от поведения reconnect конкретной версии: каждый результат браузерного инструмента проверяется против того поколения аренды, в котором он был выдан, независимо от того, сообщает ли downstream о переподключении — поэтому свежий релиз не может тихо ослабить контракт fail-closed. Процедура выбора разрешается детерминированно в следующем order:

1. --browser_command или MCP_AGENTS_BROWSER_COMMAND (строка команды или JSON argv).

2. Локальный, разрешаемый в пакете chrome-devtools-mcp, затем node_modules/.bin/chrome-devtools-mcp.

3. npx -y chrome-devtools-mcp@latest.

Третий путь может заставить первый initialize ждать разрешения npm. Для более быстрого запуска установите chrome-devtools-mcp рядом с mcp-agents или установите его в другом каталоге и укажите --browser_command на его исполняемый файл. Если вам нужна фиксированная версия для конкретного развёртывания, зафиксируйте её там. Браузерный downstream требует те же версии Node.js, которые поддерживает выпуск chrome-devtools-mcp, которым он он разрешается; собственный нижний порог этого пакета >=26 остаётся на этом уровне или выше, поскольку незафиксированная зависимость уходит за последней версией.

chrome-devtools-mcp намеренно является development-зависимостью, а не runtime-зависимостью. Поэтому локальный разработческий checkout задействует путь локального пакета, а пользователи опубликованного пакета переходят на fallback через npx, пока не установят пакет рядом с mcp-agents или не предоставят явную команду.

Размер окна передаётся хелперу лизинга, чтобы он мог установить размер окна удалённого Chromium; --viewport у Chrome DevTools MCP намеренно не передаётся, потому что при подключении через --browserUrl он бесполезен.

Каждый полностью принятый JSON-RPC кадр от downstream сбрасывает таймер простоя поколения; ошибочные сообщения на stderr и частичный вывод — нет. Освобождение по бездействию имеет 60-секундный предел на очистку, чтобы удалённый Chromium, SSH-туннели и бокс реально могли остановиться. Освобождение при выключении использует отдельный предел в 15 секунд и остаётся отслеживаемым и завершаемым. Оба случая — оптимизация стоимости по принципу best-effort. Если браузер пропадает, прерванная нативная ошибка подключения не воспроизводится повторно. Статус хелпера 69 обогащает ошибку полем browser_lease_replaced, явно предупреждая, что браузер был заменён, состояние потеряно, а результат прерванной операции неизвестен; вызывающий должен проверить состояние, а не слепо повторять вызов. Статус 0 сохраняет исходную нативную ошибку; статус 70 остаётся неизвестным, а не ошибочно интерпретируется как потерянная аренда. Следующий браузерный вызов получает нового аренда и использует путь её использования Chrome DevTools MCP.

Кадр инициализации клиента и нижестоящий запрос/ответ roots/list пересылаются без переписывания ID или URI. При перезапуске нижестоящего процесса ответы, причитающиеся завершённому процессу, отбрасываются, а его корреляции запросов аннулируются до того, как заменяющий процесс сможет переиспользовать ID. Это сохраняет локальный список разрешённых операций записи в файлы Chrome DevTools MCP, поэтому --allowUnrestrictedPaths намеренно никогда не передаётся. Сбои предварительных проверок App и MinIO выводятся отдельно и дословно. Описания Performance trace и Lighthouse предупреждают, что измерение по удалённой ссылке не является критерием приёмки, а upload_file предупреждает, что локальный путь нельзя напрямую передать удалённому Chromium.

Ограничения URL включаются по желанию, потому что режим по умолчанию, допускающий только loopback, сломал бы OAuth и сторонние ресурсы. Ужесточённое развёртывание, допускающее только loopback, может повторить, например:

--browser_allowed_url_pattern 'http://127.0.0.1/*' \
--browser_allowed_url_pattern 'https://127.0.0.1/*'

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

codex (сквозная передача)

Провайдер codex прозрачно передаёт запросы встроенному MCP-серверу Codex (codex mcp-server) внутри изолированного CODEX_HOME. Мост создаёт каждый домашний каталог внутри приватного дерева tmp/codex-homes/ в каталоге запуска сервера, копирует auth.json, записывает минимальный config.toml и не наследует ваш обычный список внешних MCP-серверов. Это не даёт Codex рекурсивно запускать другие инструменты-агенты, такие как Claude или Gemini, во время вызовов моста. Родительский и создаваемые домашние каталоги используют режим 0700; скопированные учётные данные и создаваемые файлы времени выполнения используют режим 0600.

Изолированный домашний каталог — это снимок аутентификации: он не видит более поздний codex login, пока мост не переподключится. Если Codex сообщает своё типизированное терминальное событие unauthorized, обёртка подавляет дублирующее событие и возвращает одну ошибку инструмента MCP с structuredContent.code, установленным в codex_auth_invalidated, и action, установленным в reauthenticate_and_restart. Новые витки Codex отклоняются локально, тогда как status, result, cancel, peek, ping и другие операции MCP остаются доступными. Остановите мост, выполните codex logout и codex login от имени того же пользователя ОС, проверьте с помощью codex exec, затем переподключитесь. При очистке ротированная аутентификация записывается обратно, только если изолированная копия изменилась и каноническая аутентификация всё ещё совпадает со снимком на момент запуска; поэтому устаревший мост не может перезаписать более новый ручной вход или ротацию токена другого моста.

Единственная разрешённая пользовательская настройка — Fast mode. При запуске мост читает исходный $CODEX_HOME/config.toml и включает Fast mode в изолированном домашнем каталоге, только если находит одновременно верхнеуровневый service_tier = "fast" и [features].fast_mode = true. Частичные, отключённые, отсутствующие или нечитаемые настройки оставляют Standard mode; вся остальная пользовательская конфигурация остаётся изолированной. Перезапустите MCP-сервер после изменения любого из этих параметров. Fast mode использует более высокий расход кредитов ChatGPT или тарификацию API Priority.

Прочие значения по умолчанию при запуске: sandbox_mode=workspace-write, approval_policy=never (настраивается для всего сервера через --sandbox_mode / --approval_policy), web_search=cached, check_for_update_on_startup=false, allow_login_shell=false и history.persistence=none. Фиксированные значения по умолчанию функций моста: features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false и features.skill_mcp_dependency_install=false; apps/plugins остаются отключёнными, чтобы навыки приложений/плагинов ChatGPT — Figma, Gmail, Presentations и т. д. — не попадали в контекст сеанса через мост. Встроенные субагенты дополнительно отключаются с помощью [agents] enabled = false, потому что на Codex >= 0.145.0 стабилизированного флага функции multi_agent самого по себе больше недостаточно для удаления инструментов совместной работы; сеансы вновь включают их по вызову с помощью allow_subagents (см. ниже). Эта строка [agents] учитывает версию: мост один раз при запуске проверяет codex --version и опускает её на Codex < 0.145.0, где логическое значение в [agents] является фатальной ошибкой разбора конфигурации (0.102–0.144), а флаг функции по-прежнему сам управляет инструментами совместной работы. Неподдающаяся разбору версия предполагает современный Codex.

Сеансы workspace-write имеют сетевой доступ, включённый по умолчанию, чтобы команды в песочнице могли обращаться к локальным сервисам, таким как DynamoDB, Redis, OpenSearch и MinIO. Установите --codex-workspace-network=false или MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false, чтобы отключить это для всего сервера; флаг CLI имеет приоритет над переменной окружения. Это параметр песочницы, принадлежащий серверу, и он намеренно отсутствует в схемах инструментов для отдельных вызовов.

Codex не предоставляет для этого параметра ограничение только localhost. Его включение разрешает общий исходящий сетевой доступ для команд в сеансах workspace-write. Запись в файловую систему остаётся ограниченной рабочей областью и другими настроенными корнями, доступными для записи; сеансы read-only и danger-full-access не используют параметр sandbox_workspace_write.

Мост заменяет широкую собственную схему Codex, имеющую форму конфига, намеренно компактным контрактом:

Обе схемы задают additionalProperties: false. Неподдерживаемые, отсутствующие или недопустимые аргументы отклоняются локально с кодом JSON-RPC -32602 до запуска Codex. Сюда входят собственные запасные выходы, такие как config, approval-policy, developer-instructions, base-instructions и compact-prompt; будущие дополнения вышестоящей схемы остаются скрытыми, пока mcp-agents намеренно их не примет. Значения модели за пределами двух отобранных вариантов отклоняются так же.

Встроенные субагенты. allow_subagents: true на codex или codex-start позволяет этому сеансу использовать встроенные многоагентные инструменты Codex (spawn_agent, wait_agent, …). Это ограничено сеансом точно так же, как sandbox: ответы наследуют это значение и не могут его изменить, а по умолчанию оно выключено. Внутренне флаг переключает только собственные многоагентные переключатели (agents.enabled плюс features.multi_agent, с тем же версионным ограничением, что и выше) через переопределение конфигурации для конкретного вызова; всё остальное в изолированном домашнем каталоге не меняется. В частности, вырезание [mcp_servers] остаётся в силе, поэтому порождённые субагенты — это внутрипроцессные воркеры только для Codex: они не могут повторно войти в этот мост или добраться до Claude, Gemini или любого другого внешнего MCP-инструмента, а пользовательские роли агентов из вашего настоящего $CODEX_HOME/agents/ не копируются. Остаточная оговорка касается параллелизма, а не досягаемости: субагенты наследуют sandbox_mode и approval_policy сеанса, поэтому в режиме workspace-write с approval_policy=never несколько агентов могут одновременно писать в одну и ту же рабочую область. Codex координирует их, но определяйте объём поручения с учётом этого.

approval_policy=never — это намеренный выбор для MCP-моста: отсоединённый вызов инструмента не может надёжно вести интерактивный диалог подтверждения. Операторы могут выбрать untrusted или on-request для всего сервера через --approval_policy, но вызывающие стороны не могут ослабить или изменить эту политику для отдельного запроса. Каждый новый сеанс по-прежнему должен явно указывать свою песочницу, поэтому полномочия на запись видны в месте вызова.

Флаги запуска (--model, --model_reasoning_effort) задают значения по умолчанию для изолированного встроенного сервера Codex (gpt-5.6-sol и xhigh, если не переопределены). Каждый исходный вызов codex может выбрать одну из двух моделей и один из четырёх допустимых уровней усилия рассуждений:

Селекторы применяются только при создании сеанса. Если опустить любой из них, используется значение по умолчанию, заданное на сервере. Каждый codex-reply наследует оба выбора и не может их изменить. Другие модели и уровни усилия намеренно недоступны через закрытый контракт обёртки.

Например, проверка в режиме read-only начинается с:

{
  "prompt": "Review this diff",
  "cwd": "/absolute/path/to/project",
  "sandbox": "read-only",
  "model": "gpt-5.6-terra",
  "model_reasoning_effort": "high",
  "goal": "Find correctness and security defects"
}

Внедрение цели. Задайте цель по умолчанию при запуске сервера через --goal "<text>" или передайте goal в вызове. mcp-agents внутренне превращает исходную цель в собственные developer-instructions Codex:

{
  "prompt": "Refactor the parser",
  "cwd": "/absolute/path/to/project",
  "sandbox": "workspace-write",
  "model_reasoning_effort": "xhigh",
  "goal": "Keep the public API unchanged"
}

Сообщение разработчика сохраняется для потока, поэтому ответы наследуют его. Передаваемый в вызове goal на codex-reply становится кратким напоминанием в запросе, потому что у встроенного инструмента ответа нет поля developer-instructions. Прямые инструкции разработчика не раскрываются: goal — это узкий, проверяемый интерфейс постоянной цели. Цель, переданная в вызове, переопределяет значение по умолчанию сервера; "" подавляет это значение по умолчанию для одного вызова.

Мост переписывает ответы tools/list, чтобы анонсировать эти отобранные схемы. Обычные собственные кадры остаются сквозными байт-в-байт, за исключением описанного выше типизированного сбоя аутентификации; локально генерируемые ошибки валидации и аутентификации используют ту же безопасную для кадров дисциплину очереди/границ, что и сообщения о ходе выполнения и восстановлении.

Приоритет в рамках треда. Цель, заданная в исходном вызове codex, — это сообщение от лица разработчика, действующее на весь тред, поэтому оно имеет приоритет: другая goal, поставленная позже на codex-reply, — это лишь напоминание на уровне промпта и не может надёжно переопределить зафиксированную цель (проверено вживую — ответная цель, конфликтующая с изначальной, игнорируется в пользу постоянной). Ответ-напоминание срабатывает, когда оно не противоречит зафиксированной цели. Чтобы действительно изменить цель в середине диалога, начните новый вызов codex, а не меняйте её на codex-reply.

Примечание — это не нативный /goal Codex. Штрих-команда /goal в Codex (долговечная цель уровня потока с локалью/бюджетом/подтверждением на основе фактов) — это функция только TUI — разбирается в terminal UI Codex и недоступна через codex mcp-server. Добавление к MCP-промпту префикса /goal … не активирует её; текст просто передаётся как пользовательское сообщение. Таким образом, этот враппер направляет Codex с помощью developer-instructions (нативного для MCP-средства задания постоянной цели), что является промпт/ролевой манипуляцией, а не нативным механизмом жизненного цикла цели.

Потоковая живость. Проходной кодекс отслеживает каждый открытый tools/call независимо. --codex_idle_timeout <seconds> (по умолчанию 600, 0 отключает) ограничивает, как долго один вызов может оставаться без коррелированной активности Codex. Только событие Codex, несущее этот _meta.requestId вызова (или соответствующий ответ или интерактивный обмен), обновляет его дедлайн простоя. Выводы stderr, клиентские пинги, несвязанные запросы и события, принадлежащие другому вызову, не могут поддержать зависший вызов. Если вызов достигает своего предела простоя, враппер завершает только тот вызов с ошибкой JSON-RPC (-32001), отправляет Codex notifications/cancelled для этого запроса — best-effort, то есть просит Codex остановиться, а не принуждает — и подавляет поздний диагностический ответ этого вызова, и держит соединение открытым — параллельные вызовы и stdio транспорт не затронуты. Это важно, потому что закрытие stdio-транспорта заставляет MCP-клиентов, таких как Claude Code, помечать сервер как failed и снимать с регистрации каждый mcp__codex__* инструмент на всю оставшуюся сессию (stdio-серверы не переподключаются автоматически), поэтому один зависший обзор не должен разрушать весь мост. Процессная группа Codex по-прежнему пожинается при реальном обрыве (дисконнект клиента, сигнал или stdout EPIPE). Единственное исключение: если Codex находится в зависшем состоянии на середине записи кадра ответа (нет безопасной границы для инъекции ошибки) и при этом игнорирует отмену, то враппер делает одну повторную попытку и затем переходит к ограниченному обрушению всего моста — другим способом невозможно выдать чистый кадр в частичный, поэтому клиенту остаётся переподключаться к новому мосту.

Отмена (Cancellation). Клиентская отмена (notifications/cancelled — каждый ESC, прерванный ход или демонтаж субагента) стоит ровно один запрос. --codex-cancel-grace <seconds> (по умолчанию 30) ограничивает время, в течение которого Codex может подтвердить отмену; по истечении враппер" локально закрывает этот запрос, подавляет поздний ответ Codex и оставляет мост и все остальные выполняющиеся вызовы нетронутыми. Закрыть запрос — это не доказательство, что Codex остановился; неподтверждённый ход помечается как "заброшенный" и может продолжать работать. Описанная выше промежуточная эскалация задействует вторую отсрочку, так что этот путь почти вдвое дольше, прежде чем мост финализируется. Отсрочка даётся намеренно щедро — промежуточный ход Codex выполняет команды в песочнице и не обрабатывает отмену MCP быстро, поэтому короткая отсрочка сделала бы путь эскалации путём по умолчанию. Это важнее, чем случай таймаута, потому что изолированный CODEX_HOME содержит каталог sessions/ Codex: полный снос моста делает каждый threadId в этом процессе навсегда невозобновляемым, и следующий codex-reply завершается ошибкой Session not found(сессия не найдена).

[!Warning] Отказ от запроса не останавливает Codex. Враппер просит его остановиться, но ход, игнорирующий отмену, продолжает работать и писать в рабочую директорию ещё долго после того, как клиент сдался. Каждый отказ пишется в stderr с его thread_id и job_id и логируется снова, если ход позже завершится, так что неожиданно изменённое дерево можно объяснить, а не гадать. Фоновые задания здесь — острый край: задание codex-start живёт в таблице заданий этого враппера и не в реестре задач MCP-клиента, поэтому клиентская сторона "stop" до него не дотянется — только codex-cancel со своим jobId. Поскольку задание опрашивается через этот процесс, оно никогда не сможет пережить переподключение, поэтому отключение клиента отменяет все нетерминальные задания и открытые запросы, а ограниченный wind-down пожинает группу процессов Codex, если она продолжает работать.

--timeout <seconds> также принудительно выполняется для вызовов Codex (по умолчанию 7200) как окончательный жёсткий дедлайн. Скоррелированная активность может расширить окно простоя, но никогда не этот жёсткий дедлайн. Установите дедлайн враппера ниже собственного таймаута клиента MCP, когда клиент должен всегда получать его явную ошибку, прежде чем сдаст.

Когда входящий запрос поставляет _meta.progressToken, враппер отправляет стандартные MCP notifications/progress обновления, используя точный токен. Он никогда не выдумывает токен прогресса. Первый полезный статус отображается сразу; последующие обновления объединяются не чаще одного раза в секунду, и выигрывает последний статус. Во время молчаливой работы с периодичностью раз в 10 секунд отправляется уведомление Codex: still running и включает возраст последнего запроса-коррелированного события Codex.

Текст статуса закрывается при сбое. Мост предоставляет доступ только к атрибуированным комментариям, активному шагу плана и общему жизненному циклу для команд, патчей, MCP/image-инструментов, веб-работ и субагентов. Он не предоставляет окончательный текст ответа, рассуждения, промпты, строки команд или выводы, аргументы инструментов, поисковые запросы, имена файлов или токен-телеметрию. Сообщения нормализуются по пробелам и обрубаются до 200 юникод-кодов. Родные кадры codex/event остаются байт-в-байт без изменений, за исключением того, что типизированное событие ошибки unauthorized заменяется единой структурной ошибкой аутентификации выше; прогресс — это параллельный MCP-канал и является интерфейсом пользователя, а не контекстом инструмента/результата.

Дополнительные фоновые задания. Существующие вызовы codex и codex-reply остаются блокирующими и сохраняют текущее поведение. Клиенты, нуждающиеся в обновлениях, видимых в транскрипте, могут вместо этого использовать шесть инструментов на мосту, принадлежащих обёртке:

Предпочитайте блокирующий вызов codex, включая длительные сборки. Он стоит один вызов инструмента вместо по одному ходу вызывающего на каждый статус, по-прежнему стриммит notifications/progress в UI, учитывающий прогресс, и отменяется абортом хода. Хватайтесь за задание только тогда, когда работа должна пережить вызывающего — она должна продолжиться после того, как вы перестали ждать. — или другой агент должен иметь возможность отменить её позже по jobId.

codex-peek — жив ли этот ход?

Блокирующий вызов непрозрачен, пока не вернётся, и со стороны "завис" и "занят" выглядят одинаково. codex-peek отвечает на этот вопрос, ничего не отменяя: показывает все ходы Codex в полёте, блокирующие и фоновые, доступные только для чтения и немедленные, и принимает необязательные фильтры cwd / threadId / requestId.

| requestId | Клиентский вызов, стабильный в течение всего времени жизни. Это внутренний type:value ключ враппера, а не необработанный JSON-RPC id, и не принимается notifications/cancelled | | jobId | Фоновое задание в обработчике вместо requestId, если родной запрос клиента выполняется в приватном пространстве враппера и никогда не выдаётся наружу | | state | running, canceling для хода, чья отмена не подтверждена — всё ещё выполняется, всё ещё сохраняется | | threadId | Присутствует один раз, когда Codex сообщает; называет и файл тоже | | cwd, cwdInferred, cwdUnknown | Рабочая директория; cwdInferred при восстановлении из потока, а не из вызова; cwdUnknown, когда не удалось восстановить вообще | | sandbox | Песочница (sandbox), которая была выделена на ход | | elapsedSeconds | Прошло времени с вызова — не прогресс-метрика | | lastActivitySeconds | С момента последнего коррелированного события Codex — маленькое и падающее означает хорошее состояние |

Не ищите их вместо как для каждого хода отдельный процесс: codex mcp-server является долгоживущим и мультиплексирует каждый запрос, поэтому у вас нет codex exec, который можно было бы найти, и в таблице процессов ничего не будет, пока выполняется сборка. MCP notifications/progress в IDE? Три.

ЧТО делать дальше — three:

Продолжаем перевод:

Этот результат означает меньше, чем кажется. Пустой список не является доказательством того, что ход завершился — брошенный ход продолжает работать внутри Codex, ничего не выполняется, а их количество возвращается как abandonedTurnsProcessWide — названо так по области действия, потому что заботы у брошенного хода нет, и поэтому он никогда не сужается фильтром. Большое elapsed — это не зависание, это просто настенные часы, а большое lastActivitySeconds — тоже не зависание: один вызов инструмента может выполняется длиться минутами, поэтому тишина не доказана, никогда не исправлена. Отмена — это единственное, что нельзя отменить. А фильтр cwd никогда не скрывает ход, чей рабочий каталог неизвестен — он сообщает об этом с помощью cwdUnknown, потому что "не могу сказать" не должно тихо становиться "ничего не работает".

Начальный результат — непрозрачный jobId с cursor и часто следующей подсказкой. Повторные вызовы codex-status возвращают обычные результаты MCP, поэтому внешний агент или субагент могут передавать, что делает Codex, даже если его UI не отображает notifications/progress — это единственная особенность, которую прямая работа даёт. вызовы блокируются — не отображаются.

**Ожидание прогресса.

Разблокированный вызов — пока не отобразит исключение. Не "wedged", "busy".

--codex-idle-timeout <seconds> (по умолчанию 600, 0 отключает) ограничивает, как долго один вызов может обходиться.

Translation seems tricky. We need to ensure the Markdown is preserved. Let's continue.

A blocking call is opaque until it returns, which makes "wedged" and "busy" look identical from outside. codex-peek answers that without cancelling anything, it lists every Codex turn in flight, including blocking and background, read-only and immediate, and accepts optional cwd / threadId / requestId filters.

Do not look for a per-turn process instead: codex mcp-server is long-lived and multiplexes every request, so there is no codex exec to find, and a process-table check reports nothing while a build is running.

Three answers that mean less than they look. An empty list is not evidence that a turn finished — an abandoned turn it keeps running inside Codex with nothing in flight left to report, and their count: abandonedTurnsProcessWide, named for its scope, because an abandoned turn retains no workspace and so is never narrowed by a filter. A large elapsed is not a stall — it is only wall clock — and a large lastActivitySeconds is not a stall either: a single tool call can legitimately run silent for many minutes, so quiet is unproven, never fixed. Cancelling to find out is the one thing that cannot be undone. And a cwd filter never hides a turn whose workspace is unknown — it reports it with cwdUnknown, because "I cannot tell" must not become "nothing is running there".

Different — это определенно не то же самое, что и "ничего не работает".

The start result returns an opaque jobId and cursor, usually a suggested next suggestion. Repeated codex-status calls return ordinary MCP results, so an outer agent or subagent can relay what Codex is doing even when its UI does not render progress events — the visibility a direct job offers. A blocking call does not. At the current cursor, a status call waits for a change; heartbeat only, wait_ms may be set from 0 to 60000, and when omitted, defaults to the status interval Value

Output should be accurate.

Let's continueПриоритет в рамках треда. Цель, поставленная при первоначальном вызове codex, — это сообщение от лица разработчика и действует на весь тред, поэтому оно имеет приоритет: другая цель goal, указанная позже на codex-reply, — это лишь напоминание на уровне подсказки и не может надежно переопределить зафиксированную цель (проверено вживую — ответная цель, конфликтующая с первой, игнорируется в пользу первой). Напоминание-ответ срабатывает, когда оно не противоречит зафиксированной цели. Чтобы по-настоящему сменить направление на полпути, начать новый вызов codex, а не менять её на codex-reply.

Примечание — это не родной /goal в Codex. Слэш-команда Codex /goal (долговечная цель треда с локалью/бюджетом/завершением на основе фактов) — это функция исключительно TUI: разбирается в терминальном UI Codex и недоступна через codex mcp-server. Если к MCP-промпту добавить префикс /goal …, это не активирует её. Текст просто прозрачно пропускается как пользовательское сообщение. Этот враппер, следовательно, направляет Codex через developer-instructions (нативный для MCP инструмент для текущей цели), что является обусловливанием промпта/роли, а не нативным жизненным циклом цели.

Активность каждого вызова. Каждый открытый tools/call Codex отслеживается независимо. --codex-idle-timeout <seconds> (по умолчанию 600, 0 выключает) ограничивает, как долго один вызов может находиться без коррелированной активности Codex. Только событие Codex, несущее этот _meta.requestId (или согласованный ответ/интерактивный обмен), обновляет его дедлайн простоя. Ошибки stderr, пинги клиентов, несвязанные запросы и события, принадлежащие другому вызову, не могут оживить остановившийся вызов. Если вызов достиг дедлайна простоя, враппер завершает только этот вызов ошибкой JSON-RPC (-32001), отправляет Codex notifications/cancelled для этого запроса — наилучшим образом, то есть просит Codex остановиться, а не принуждает — подавляет поздний диагностический ответ этого вызова и оставляет соединение открытым — со смежные вызовы и stdio-транспорт не затронуты. Это важно, потому что закрытие stdio-транспорта заставляет MCP-клиентов, таких как Claude Code, помечать сервер как failed и навсегда снимать с регистрации каждый инструмент mcp__codex__* на оставшуюся часть сессии (stdio-серверы не переподключаются автоматически), поэтому один застопорившийся обзор никогда не должен обрушить весь мост. Процессная группа Codex по-прежнему собирается при настоящем обрыве (отключение клиента, сигнал или stdout EPIPE). Единственное исключение: если Codex застрял на полпути через запись кадра ответа (нет безопасной границы для введения ошибки) и игнорирует отмену, враппер предпринимает одну повторную попытку, а затем переходит к ограниченному обрыву всего моста — нет способа испустить чистый кадр в частичный кадр. невозможно

Завершают ожидание статуса две вещи, и обе важны для стоимости опроса. Продвижение курсора регулируется на стороне сервера параметром --codex_status_interval <seconds> (по умолчанию 30), который объединяет промежуточный прогресс в один шаг вместо того, чтобы сдвигать курсор при каждом сообщении. Второе — heartbeat wait_ms, и этим интервалом он не ограничивается: поэтому wait_ms теперь повторяет статусный интервал (с потолком 60000, так что при интервале больше 60 секунд heartbeat всё равно происходит каждые 60), чтобы heartbeat не обгонял курсор, о котором он сообщает. wait_ms остаётся потолком для простаивающего ожидания и никогда не становится нижней границей интервала между опросами: статусный вызов возвращается немедленно, если курсор уже отстал от головы. Опросчик, который отстал, этим значением замедлить нельзя, — а вот тот, кто догнал, может быть замедлен; именно поэтому снижение wait_ms ничего не даёт, а только впустую тратит опросные раунды.

Регулируется только промежуточный прогресс; переходы жизненного цикла — первое running, отмена и любое терминальное состояние — сдвигают курсор и будят всех ожидающих напрямую, минуя интервал, так что его увеличение никогда не откладывает завершение. Обнаружение зависаний на это также не влияет — lastActivitySeconds проставляется из сырых событий Codex, а не из статусных тиков, — и codex-commentary по-прежнему хранит полную историю. 0 возвращает продвижение курсора при каждом изменении; значения выше 60 оставляют главным потолок heartbeat и только позволяют статусному тексту устаревать. У уведомлений о ходе выполнения собственная, гораздо более частая периодичность, и вызывающей стороне они не стоят контекста — но имейте в виду: они приходят только для блокирующего вызова. В запросе фоновой задачи нет токена прогресса, поэтому фоновой задаче видна только пара codex-status / codex-commentary.

Когда commentaryEndOffset продвигается, вызывайте codex-commentary с последним nextOffset. Комментарий содержит только те сообщения Codex, которые явно помечены фазой commentary. Скрытые рассуждения, промпты, черновики финального ответа, командные строки и их вывод, аргументы инструментов, пути, поисковые запросы и сырые элементы ответа в него не включаются. Небезопасные терминальные управляющие последовательности вырезаются, но оставшийся текст создан моделью и по-прежнему должен считаться недоверенным. Смещения отсчитываются в кодовых точках Unicode. Каждое чтение возвращает не более 32 768 кодовых точек; мост хранит последний хвост размером в один МиБ в UTF-8 и сообщает абсолютные границы усечения, когда более старые комментарии уже вышли из буфера.

Как только статус становится терминальным, используйте codex-result и продолжайте с nextOffset, пока done не станет true. Каждая страница возвращает свои данные и как обычный текстовый контент MCP, и как structuredContent.text для клиентов, которые предпочитают структурированные результаты. Страницы результата тоже ограничены 32 768 кодовыми точками. Если между кадр результата больше лимита захвата моста в 10 МиБ, задача атомарно завершается с ошибкой, вместо того чтобы приватный ответ утёк на MCP-транспорт.

Задачи намеренно привязаны к соединению: перезапуск или переподключение MCP-сервера их теряет. Одновременно может быть активно не больше восьми задач и сохранено не больше 32 записей; терминальные записи истекают через час. Отмена обладает той же ограниченной семантикой завершения, что и блокирующий вызов, поэтому перед повторном запуске отменённой задачи с возможностью записи осмотрите рабочее дерево. API задач подключается на уровне вызова и не требует поддержки MCP Tasks со стороны клиента.

Эти уведомления намеренно не дают погаснуть окну простоя для клиента, следящего за прогрессом; право судить о живости остаётся за idle- и жёсткими дедлайнами обёртки. Они не обновляют --codex_idle_timeout, не продлевают жёсткий дедлайн обёртки и не расширяют отдельный жёсткий таймаут инструмента по настенным часам у клиента. Сгенерированный кадр прогресса вставляется только на границе нативной строки; если Codex замирает на середине кадра, свежее уведомление ждёт безопасной границы, а настоящий сторожевой таймаут по-прежнему завершит постоянное зависание. Настройте клиентский таймаут так, чтобы он превышал самый длинный ожидаемый запуск Codex плюс запас на ответ; когда он истекает, клиент отменяет вызов и затем подхватывает ограниченный путь отмены ниже.

Восстановление терминального результата. Codex объявляет идентификатор потока в раннем событии сессии, для коррелированном с запросом, поэтому обёртка сохраняет его до завершения работы. Если далее Codex испускает своё терминальное событие завершения и финальное сообщение агента, но его нативный ответ на tools/call не приходит в течение короткого льготного периода терминального ответа, обёртка возвращает эквивалентный успешный результат, содержащий и content, и structuredContent.threadId. Соответствующий поздний нативный ответ отбрасывается, что сохраняет семантику ровно одного JSON-RPC response. Это закрывает ситуацию, когда результат работы уже попал в дерево, но вызывающая сторона не получила ни результата, ни идентификатора потока.

Отмена и переподключение. Отмена клиента запускает короткий несбрасываемый льготный период, ограниченный параметром --codex_cancel_grace (описанная ниже эскалация на середине кадра включает второй такой период, поэтому этот путь может занять примерно в два раза дольше). Если Codex не укладывается в льготный период, обёртка локально закрывает этот идентификатор запроса, подавляет поздний ответ Codex и оставляет работать и мост, и все смежные вызовы — один застрявший вызов не должен обрушивать весь мост. Два ограниченных исключения: поток, застрявший на середине кадра и та же игнорирующий отмену (когда нет безопасной границы, чтобы вставить ошибку, обёртка пробует ещё раз и затем переходит к разбору всего моста), и сумму лимит — как только количество подавленных ответов достигает MAX_SUPPRESSED_CODEX_RESPONSES, мост завершает работу, а не хранит их бесконечно. После любого из этих случаев клиент переподпосоединяется к новому мосту. Поздний нативный ответ, пришедший в течение льготного периода, отбрасывается, если его можно перехватить без повреждения уже отправленного частичного кадра. Отменённый и потенциально способный на запись вызов никогда автоматически не повторяется. Отмена — это best-effort и не доказывает, что Codex остановился: неподтверждённый ход записывается как брошенный, а не завершённый, и может продолжать работу и запись в рабочем дереве; поэтому перед выполнением вручную осмотрите рабочее дерево.

Этот легаси-мост намеренно не перезапускает codex mcp-server внутри существующего stdio-соединения и не прозрачно воспроизводит потоки заново. Состояние codex-reply принадлежит старому процессу Codex, поэтому идентификатор потока разрушенного дочернего процесса после переподключения возобновить нельзя. Устойчивое восстановление в том же соединении требует отдельной миграции: от прозрачной легаси-прокладки к MCP-адаптеру поверх codex app-server (thread/start, turn/start, turn/interrupt и thread/resume).

Интеграция с Claude Code

Добавьте записи в .mcp.json вашего проекта, используя глобально установленный бинарник mcp-agents:

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex"],
      "timeout": 7500000
    },
    "gemini": {
      "command": "mcp-agents",
      "args": ["--provider", "gemini"]
    }
  }
}

npm (глобальная установка) vs npx — выбирайте глобально установленный бинарник. Форма command: "mcp-agents" выше запускает локально установленный бинарник напрямую; альтернатива через npx ниже выполняет npx -y mcp-agents при каждом старте процесса. Это важнее не только для скорости холодного запуска: Claude Code перезапускает stdio-сервер всякий раз, когда (пере-) подключается — в том числе после переподключения в середине сессии, — а npx на каждом запуске делает разрешение пакета через npm-реестр, без запасного пути офлайн. Если это разрешение медленно работает (VPN, копитивный портал, сбой реестра), даёт устаревший kếш до версии, которой больше нет (npm error code ETARGET), или иным образом падает — запуск падает, транспорт закрывается, и сессия теряет инструменты. Globally установленный бинарник (или абсолютный путь к node server.js) убирает сетевую зависимость и один уровень процессов из пути сигналов/разрушения. Установите один раз: npm install -g mcp-agents (или npm link из исходников), после чего укажите на него конфиг.

Для локальной сборки из исходников, используемой как ваш личный мост Codex, в записи на уровне пользователя ~/.claude.json можно запускать дерево напрямую и отключить ограничение простоя на запрос (тогда длинная и легитимно тихая проверка будет ограничена только собственным таймаутом клиента по часам, а не завершена преждевременно):

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-agents/server.js", "--provider", "codex", "--codex_idle_timeout", "0"],
      "env": {},
      "timeout": 3600000
    }
  }
}

Голый node ищется через PATH MCP-клиента; если node управляется менеджером версий (nvm/fnm/asdf), который не инициализирован в этом окружении, укажите абсолютный путь к node (which node, например /opt/homebrew/bin/node).

Переопределите настройки codex по умолчанию при запуске сервера:

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex", "--model", "gpt-5.6-sol", "--model_reasoning_effort", "xhigh", "--codex-workspace-network=false"],
      "timeout": 7500000
    }
  }
}

Каждый начальный для отдельного вызова codex может выбирать gpt-5.6-sol or gpt-5.6-terra и один из режимов medium, high, xhigh или max; если селекторы не заданы, используются значения сервера по умолчанию, а ответы наследуют оба выбора. Другие модели, raw config и аргументы, задающие политику одобрения на один вызов, отклоняются до запуска Codex. Добавьте "--goal", "<text>" в массив args, чтобы задать цель по умолчанию (см. Внедрение goal выше).

Claude интерпретирует timeout в миллисекундах как жёсткий лимит по настенным часам; прогресс его не продлевает. Держите его выше --timeout обёртки (по умолчанию 7 200 секунд) и оставляйте запас на ответ. Запись в проектном .mcp.json может перекрывать пользовательскую MCP-запись с тем же именем, поэтому размещайте таймаут в проектной записи, а не полагайтесь на копию на уровне пользователя.

Кроме явной пары Fast-mode из описанного выше, мост не наследует настройки из обычного ~/.codex/config.toml. В частности, унаследованные MCP-серверы в сессиях прокинутого Codex намеренно недоступны.

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "mcp-agents", "--provider", "codex"],
      "timeout": 7500000
    }
  }
}

npx влияет только на запуск процесса: после подключения задержка вызова одного и та же, потому что выполняется один и тот же код сервера. Но каждый запуск, включая каждое переподключение, проверяет пакет в npm-реестре без безопасного офлайн-режима, поэтому медленный, офлайн-сценарий или закек к версии, которой больше нет, может сломать запуск и отобрать инструменты посреди сессии (см. npm vs npx выше). Задание конкретной версии mcp-agents@x.y.z защищает от того, чтобы в середине сессии @latest подхватил только вышедший релиз, но не убирает сетевую зависимость на каждом запуске. Используйте npx, только если нулевая установка важнее надёжности запуска.

Интеграция с OpenAI Codex

Добавьте в ~/.codex/config.toml две записи — по одной для каждого провайдера, который должен быть доступен. Таймаут клиента Claude 960 секунд сохраняет совместимость с блокирующим инструментом claude_code с таймаутом 900. Фоновые проверка не держит MCP-запрос открытым: claude-start возвращается сразу, а каждый вызов claude-status длится не более 60 секунд.

[mcp_servers.claude-code]
command = "mcp-agents"
args = ["--provider", "claude"]
tool_timeout_sec = 960

[mcp_servers.claude-code.tools.claude-start]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-status]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-result]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-cancel]
approval_mode = "approve"

[mcp_servers.gemini]
command = "mcp-agents"
args = ["--provider", "gemini"]
tool_timeout_sec = 360

В сессии Codex запросите второе мнение или проверку у Claude и используйте claude-start → claude-status → claude-result. claude_code оставьте для маленьких блокирующих запросов; generator gemini gem остаётся блокирующим инструментом.

Разработка

npm install
npm link          # symlinks mcp-agents to your local server.js

После npm link любые изменения в server.js вступают в силу сразу — переустанавливать не нужно.

Замерьте пути запуска на реальных файлах .mcp.json проекта в /tmp:

npm run bench:mcp-startup

Замеряет запуск MCP протокола через initialize и tools/list; он не вызывает модель/инструмент провайдера.

Для ручной фоновой проверки Claude вызовите claude-start с коротким промптом анализа и этим репозиторием как cwd, опрашивайте claude-status с каждым возвращённым курсором и прочьте вердикт через claude-result. В обратном направлении пусть Claude Code вызывает codex-start, опрашивает codex-status и читает codex-result. Эти смоуки-проверки используют реальные вызовы моделей и остаются за пределами детерминированного тестового прохода.

Как это работает

1. По stdio подключается MCP-клиент.

2. Сервер читает --provider <name> из своих аргументов (по умолчанию codex).

3. Gemini регистрирует один блокирующий инструмент; Claude регистрирует свой легаси-блокирующий инструмент и одноразовые задачи проверки; Codex пробрасывает свои нативные инструменты и добавляет инструменты фоновых задач.

4. Клиент вызывает полный инструмент с указанным именем и prompt.

5. Сервер запускает CLI как отсоединённый дочерний процесс; проверки Claude разбирают потоковый JSON (stream-json) на безопасные статусы и сохраняемые страницы результата, а блокирующие инструменты возвращают нормализованный вывод провайдера.

Сервер поддерживает небольшой таймер keepalive, чтобы Node.js не завершался преждевременно, когда stdin достигает EOF до того, как асинхронный подпроцесс зарегистрирует активный дескриптор. В режиме провайдеров Claude и Gemini этот keepalive очищается при остановке. Когда соединение MCP stdio закрывается, активные задания Claude получают прерывание и ограниченный по времени запасной вариант TERM/KILL; все оставшиеся отслеживаемые отсоединённые группы процессов провайдеров завершаются перед выходом сервера.

Лицензия

MIT