Как подключить Codex к n8n: выберите один из трёх маршрутов — встроенный MCP-сервер инстанса n8n (включить MCP-доступ, скопировать Server URL, добавить сервер в Codex), сторонний n8n-MCP через TOML в ~/.codex/config.toml или шлюз One с командой codex mcp login one. Ниже — выбор маршрута, готовые конфиги и проверка результата.
Таблица выбора маршрута
Маршруты различаются тем, что именно вы подключаете и где живёт конфигурация. Встроенный MCP-сервер инстанса n8n описан в документации n8n: он даёт клиенту доступ к воркфлоу, помеченным как доступные в MCP, и работает через единое подключение на инстанс. Сторонний n8n-MCP — отдельный сервер, который запускается локально командой npx и прописывается в конфиг Codex. Шлюз One — посредник: по данным withone.ai, он даёт дойти до n8n либо через One CLI, либо через удалённый MCP-сервер One.
| Критерий | Встроенный MCP инстанса n8n | Сторонний n8n-MCP | Шлюз One |
|---|---|---|---|
| Что подключается | MCP-сервер самого инстанса n8n | Локальный сервер n8n-mcp через npx |
Удалённый MCP-сервер One |
| Где задаётся конфиг | Диалог Connect a client в n8n, затем клиент Codex | ~/.codex/config.toml, секция [mcp_servers.n8n] |
~/.codex/config.toml плюс codex mcp login one |
| Нужны N8N_API_URL и N8N_API_KEY | Нет, авторизация через OAuth или API key инстанса | Опционально: без них доступен только справочный слой | Нет, доступ идёт через аккаунт One |
| Как авторизоваться | OAuth (рекомендуется) или API key | Ключ n8n в N8N_API_KEY либо ничего для справочного слоя |
OAuth со скоупом через codex mcp login one |
| Как проверить | /mcp в Codex, затем простой запрос |
/mcp, затем поиск узла |
/mcp, затем запрос к n8n |
| Кому подходит | Тем, у кого есть права владельца или админа инстанса | Тем, кто хочет локальный сервер и тонкую настройку | Тем, кто подключает несколько сервисов через один шлюз |
Предпосылки для встроенного маршрута: права владельца или администратора инстанса, потому что включение MCP-доступа требует этих прав. Для стороннего n8n-MCP нужен Node.js с npx. Для шлюза One нужен аккаунт One и установленный One CLI либо готовность добавить удалённый сервер.
Отдельно стоит различать MCP-доступ на уровне инстанса и узел MCP Server Trigger. Документация n8n объясняет: доступ на уровне инстанса создаёт одно подключение на инстанс, использует централизованную аутентификацию и позволяет выбрать, какие воркфлоу открыть. Узел MCP Server Trigger настраивается внутри одного воркфлоу и открывает инструменты только из него.
Конфиг Codex для стороннего n8n-MCP
Сторонний сервер n8n-mcp прописывается в файл ~/.codex/config.toml. Документация проекта на mintlify.com указывает: добавьте в config.toml секцию [mcp_servers.n8n] с командой запуска. Базовая версия даёт справочный слой — знание об узлах n8n без доступа к вашему инстансу.
[mcp_servers.n8n]
command = "npx"
args = ["-y", "n8n-mcp"]
env = { MCP_MODE = "stdio", LOG_LEVEL = "error", DISABLE_CONSOLE_OUTPUT = "true" }
Полная версия добавляет доступ к вашему инстансу через переменные окружения. Документация проекта называет их N8N_API_URL и N8N_API_KEY. В примере ниже ключ записан прямо в поле env, как в документации проекта, поэтому такой файл не публикуйте и не добавляйте в репозиторий. Документация Codex описывает поле env_vars, которое пробрасывает серверу разрешённые переменные из окружения, так что ключ можно держать вне файла.
[mcp_servers.n8n]
command = "npx"
args = ["-y", "n8n-mcp"]
env = { MCP_MODE = "stdio", LOG_LEVEL = "error", DISABLE_CONSOLE_OUTPUT = "true", N8N_API_URL = "https://ваш-домен", N8N_API_KEY = "ваш-ключ" }
Что меняется под вас: N8N_API_URL — адрес вашего инстанса, N8N_API_KEY — ключ из настроек n8n. Значения MCP_MODE, LOG_LEVEL и DISABLE_CONSOLE_OUTPUT оставьте как в примере. После правки конфига перезапустите Codex, чтобы он перечитал файл.
Документация Codex на learn.chatgpt.com описывает и более тонкие поля той же секции. Поле command задаёт команду запуска сервера, args — аргументы, env — переменные для сервера, env_vars — переменные, которые разрешено пробрасывать. Поля startup_timeout_sec и tool_timeout_sec задают таймауты запуска и выполнения инструмента. Поле enabled = false отключает сервер без удаления секции.
Проверка после настройки: в TUI Codex выполните /mcp. Документация Codex указывает, что эта команда показывает активные MCP-серверы. Сторонний n8n-mcp в списке появится под именем n8n. Если сервер не виден, проверьте, что npx доступен в PATH и что конфиг лежит именно в ~/.codex/config.toml.
Конфиг для удалённого MCP-сервера One
Шлюз One подключается как удалённый MCP-сервер. По данным withone.ai, дойти до n8n можно двумя способами: через One CLI или добавив MCP-сервер One в Codex. Оба пути ведут к одному подключению n8n.
Сначала добавьте сервер One в конфиг Codex. Адрес сервера — https://mcp.withone.ai/mcp, имя сервера в примере — one.
[mcp_servers.one]
url = "https://mcp.withone.ai/mcp"
Затем выполните авторизацию. Документация withone.ai указывает команду codex mcp login one. При входе запрашивается скоуп доступа — набор разрешений, которые шлюз получает к вашему аккаунту. Выдавайте минимально нужный скоуп.
codex mcp login one
Что меняется под вас: имя сервера one в команде входа должно совпадать с именем секции в конфиге. Если вы назвали секцию иначе, подставьте своё имя. Адрес https://mcp.withone.ai/mcp — это адрес шлюза, его не заменяют на адрес вашего инстанса n8n.
Альтернативный путь — One CLI. Документация withone.ai описывает команды one init и one add n8n. Этот способ удобен, когда вы подключаете несколько сервисов и хотите управлять ими из одной консоли. После добавления n8n через CLI тот же сервер One становится доступен Codex.
Проверка: выполните /mcp в Codex и убедитесь, что сервер one в списке. Затем задайте простой запрос — например, попросите перечислить доступные воркфлоу n8n. Если шлюз вернул список, авторизация прошла.
Маршрут встроенного MCP-сервера n8n
Встроенный MCP-сервер инстанса n8n — самый прямой маршрут. Документация n8n описывает порядок: включить MCP-доступ на инстансе, скопировать Server URL, настроить клиент Codex, завершить авторизацию.
Шаг 1. Включение MCP-доступа. Перейдите в Settings > Instance-level MCP. Выберите Enable MCP access. Документация n8n указывает, что для этого нужны права владельца или администратора инстанса. После включения страница делится на три раздела: Connection details, Access и Connected clients.
Шаг 2. Копирование Server URL. В разделе Connection details нажмите Connect, чтобы открыть диалог Connect a client. Документация n8n указывает, что этот диалог доступен с версии n8n 2.33.0. В диалоге выберите вкладку OAuth (рекомендуется), затем в списке Your client выберите Codex. n8n группирует клиентов на CLI, Web и IDE; Codex попадает в группу CLI.
Шаг 3. Настройка клиента Codex. Документация n8n приводит команду для добавления сервера:
codex mcp add n8n --url "https://<ваш-домен-n8n>/mcp-server/http"
Альтернатива — ручная секция в ~/.codex/config.toml. Документация n8n приводит такой вариант для OAuth:
[features]
experimental_use_rmcp_client = true
[mcp_servers.n8n]
url = "https://<ваш-домен-n8n>/mcp-server/http"
Блок [features] с experimental_use_rmcp_client включает HTTP MCP-клиент Codex. Документация n8n поясняет: он нужен старым сборкам Codex, новые сборки его игнорируют. Не считайте его обязательным для свежей версии.
Шаг 4. Авторизация. Документация n8n указывает команду codex mcp login n8n для завершения OAuth. При первом подключении клиент перенаправит вас в n8n, где нужно одобрить доступ.
Шаг 5. Перезапуск клиента. После правки конфига перезапустите Codex. Документация Codex отмечает, что ChatGPT desktop, Codex CLI и расширение для IDE делят одну конфигурацию MCP, поэтому настройка переносится между ними.
Вариант с API key вместо OAuth: в диалоге переключитесь на вкладку API key. Документация n8n указывает, что n8n автоматически создаёт персональный токен доступа, привязанный к вашей учётной записи, при первом открытии вкладки. Скопируйте Server URL и токен и добавьте в ~/.codex/config.toml секцию из документации n8n:
[mcp_servers.n8n-mcp]
url = "https://<ваш-домен-n8n>/mcp-server/http"
http_headers = { "authorization" = "Bearer <ваш-токен>" }
Вместо <ваш-домен-n8n> и <ваш-токен> подставьте скопированные Server URL и токен. Документация n8n предупреждает: после ухода с вкладки n8n показывает только замаскированное значение токена, и скопировать его заново можно лишь после ротации.
http и https: какой префикс ставить
Префикс Server URL зависит от того, как обслуживается ваш инстанс. Документация n8n формулирует правило: примеры используют https://, а если инстанс отдаёт обычный HTTP, например локальная установка на http://localhost:5678, ставьте http://. Копирование полного Server URL из n8n даёт правильный префикс в обоих случаях.
| Ситуация | Префикс Server URL | Пример |
|---|---|---|
| Локальный инстанс без TLS | http:// |
http://localhost:5678/mcp-server/http |
| Облачный инстанс n8n | https:// |
https://ваш-инстанс.app.n8n.cloud/mcp-server/http |
| Self-hosted с TLS | https:// |
https://n8n.example.com/mcp-server/http |
Документация n8n отдельно предупреждает: Server URL заканчивается на /mcp-server/http, и это адрес не редактора n8n. Не вставляйте URL из адресной строки браузера. Полный Server URL виден в n8n в разделе Settings > Instance-level MCP > Connect a client > Server URL.
Частая причина сбоя — смешение схемы и порта. Локальный инстанс на http://localhost:5678 не отвечает по https://localhost:5678, потому что TLS на нём не настроен. Скопированный из n8n Server URL снимает этот вопрос.
Если инстанс стоит за обратным прокси, балансировщиком или веб-приложением-фаерволом, документация n8n советует проверить, что они не срезают заголовки MCP-запроса: MCP-Protocol-Version, Mcp-Method и Mcp-Name. Прокси, который пропускает только белый список заголовков, добавляет эти три в список. Иначе клиент может не подключиться или откатиться на старую версию протокола.
Проверка результата
Проверка идёт в три шага: команда /mcp, список инструментов, первый запрос.
Шаг 1. Команда /mcp. Документация Codex указывает, что в TUI Codex команда /mcp показывает активные MCP-серверы. Выполните её и убедитесь, что сервер n8n в списке. Документация Codex также отмечает: список серверов показывает, какие из них включены и какие требуют OAuth. Если сервер помечен как требующий входа, выберите Authenticate.
Шаг 2. Список инструментов. Документация n8n описывает, что MCP-сервер инстанса открывает инструменты для управления воркфлоу, сборки воркфлоу, управления агентами и работы с таблицами данных. Полный перечень с параметрами — в справочнике MCP server tools reference. Убедитесь, что нужные инструменты видны.
Шаг 3. Первый запрос. Начните с простого действия. Для стороннего n8n-MCP подойдёт поиск узла: документация проекта на mintlify.com относит поиск узлов к его инструментам. Для встроенного MCP-сервера инстанса подойдёт поиск воркфлоу. Документация n8n указывает, что инструмент search_workflows отдаёт превью всех воркфлоу, к которым у текущего пользователя есть доступ. Если поиск вернул результат, подключение работает.
Готовый промпт для первого запроса:
Покажи список воркфлоу n8n, доступных через MCP, и для каждого выведи название и краткое описание. Затем найди узел [название узла] и покажи его параметры.
Что меняется под вас: [название узла] замените на узел, который ищете, например HTTP Request или Set. Если хотите проверить выполнение, попросите запустить тестовый воркфлоу, помеченный как доступный в MCP.
Вариации того же первого запроса:
Перечисли инструменты, которые MCP-сервер n8n отдаёт тебе сейчас, и коротко опиши назначение каждого.
Найди воркфлоу с описанием [ключевое слово] и покажи, какие узлы в нём используются.
Создай черновик воркфлоу из двух узлов: [узел 1] и [узел 2], и покажи его перед сохранением.
Проверь, какие воркфлоу помечены как доступные в MCP, и выведи их список с датами изменения.
Открой воркфлоу [имя] и объясни, что он делает, по его узлам и связям.
Если /mcp не показывает сервер, проверьте три вещи: MCP-доступ включён на инстансе, нужные воркфлоу помечены как доступные в MCP, способ аутентификации в клиенте настроен верно. Документация n8n перечисляет эти проверки в разделе Troubleshooting.
Границы и предупреждения
Несколько ограничений важно учесть до настройки.
Превью-статус агентов. Документация n8n указывает, что агенты находятся в статусе Preview и могут меняться в будущих релизах. Для продакшн-воркфлоу на них полагаться не стоит. Управление агентами через MCP доступно с версии n8n 2.34.0.
Скоуп прав. Документация n8n поясняет: каждый подключённый клиент получает только те права, которые вы выдали при подключении, например чтение воркфлоу без возможности их создавать или запускать. Проверить и отозвать доступ можно в разделе Connected clients. Клиенты с API key в этом списке не появляются, потому что аутентифицируются bearer-токеном. В разделе Connected clients видны только OAuth-подключения.
Доступ к воркфлоу. Документация n8n подчёркивает: MCP не открывает все воркфлоу инстанса разом. Нужно включить MCP на уровне инстанса, а затем отдельно для каждого воркфлоу. Исключение — search_workflows, который видит все воркфлоу, доступные текущему пользователю, но возвращает только превью, без полных данных. Клиенты не могут читать, запускать или изменять воркфлоу, пока вы явно не включите для него MCP-доступ.
Видимость между клиентами. Документация n8n отмечает: MCP-доступ не разграничивается по клиентам. Все подключённые клиенты видят все воркфлоу, включённые для MCP. Ограничить конкретные воркфлоу конкретными клиентами нельзя. На уровне пользователя видимость сохраняется: пользователь видит только те воркфлоу с MCP, к которым у него есть доступ.
Отключение. Документация n8n указывает: в разделе Connection details выберите управление статусом MCP и Disable. n8n запросит подтверждение, потому что отключение разрывает связь со всеми подключёнными клиентами и отзывает их доступ. Для полного удаления функции на self-hosted задайте переменную N8N_DISABLED_MODULES=mcp.
Ошибка прав при авторизации. Документация n8n описывает случай: клиент отправляет вас в n8n одобрить доступ, а вы попадаете на страницу с сообщением о недостатке прав. Для MCP-сервера инстанса это означает, что MCP-доступ не включён. Пока сервер работает, любой вошедший пользователь может одобрить клиента; пока доступ выключен, n8n отказывает всем. Попросите владельца или администратора включить доступ и подключите клиент заново.
Частые вопросы
Что такое n8n codex и как они связаны?
Codex — агент, который умеет работать с внешними системами через MCP. n8n отдаёт свой MCP-сервер, и Codex подключается к нему как клиент. После подключения Codex видит инструменты n8n и может искать воркфлоу, читать их и запускать. Связь настраивается через конфиг Codex и настройки MCP в n8n.
Какой маршрут выбрать для подключения Codex к n8n?
Если у вас есть права владельца или администратора инстанса, берите встроенный MCP-сервер n8n: он даёт единое подключение и централизованную аутентификацию. Сторонний n8n-MCP подойдёт, когда нужен локальный сервер и тонкая настройка через config.toml. Шлюз One выбирайте, когда подключаете несколько сервисов через один посредник.
Почему Codex не видит сервер n8n после настройки?
Проверьте три вещи. MCP-доступ включён на инстансе. Нужные воркфлоу помечены как доступные в MCP. Способ аутентификации в клиенте настроен верно. Документация n8n перечисляет эти проверки в разделе Troubleshooting. Также убедитесь, что после правки конфига Codex перезапущен.
Какой префикс ставить в Server URL для локального n8n?
Для локальной установки на http://localhost:5678 ставьте http://. Документация n8n указывает, что примеры используют https://, а для инстанса с обычным HTTP нужен http://. Копирование полного Server URL из n8n даёт правильный префикс. Server URL заканчивается на /mcp-server/http.
Что делать, если при авторизации пишет о недостатке прав?
Для MCP-сервера инстанса это означает, что MCP-доступ не включён. Документация n8n указывает, что при выключенном доступе n8n отказывает всем пользователям. Попросите владельца или администратора инстанса включить MCP-доступ в Settings > Instance-level MCP. После этого подключите клиент заново.