claude-openrouter-delegate-mcp

Delegate tasks from an Anthropic-backed Claude Code session to OpenRouter-backed Claude Code sessions — without the two ever sharing environment variables.

Pointing Claude Code at OpenRouter means exporting ANTHROPIC_* variables into your shell. Those variables are process-wide, so one shell is either "Anthropic" or "OpenRouter", never both — and an exported ANTHROPIC_AUTH_TOKEN holding your OpenRouter key is one stray subprocess away from leaking.

This MCP server spawns each delegated session as a child process with an explicitly constructed environment. Your Opus session keeps its own credentials; the delegate gets OpenRouter's. They run side by side in the same terminal.

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: openrouter ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=https://openrouter.ai/api
                                       ANTHROPIC_AUTH_TOKEN=sk-or-v1-…
                                       → deepseek/deepseek-v4-flash-0731

This is a sibling of claude-ollama-delegate-mcp, which does the same thing for a local Ollama server. The difference that shapes everything here: OpenRouter costs real money and offers 400+ models, so this package adds an API-key path, a model catalog with prices, and per-job cost reporting.

Quick start

# 1. an OpenRouter API key: https://openrouter.ai/keys
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. register the server
claude mcp add openrouter --scope user -- npx -y claude-openrouter-delegate-mcp

# 3. restart your Claude Code session

Then ask for delegation in plain language:

delegate this to openrouter: summarise every exported symbol in src/

By default the server only delegates when you explicitly ask. To let the orchestrator decide for itself, see Delegation modes.

Related MCP server: Ollama MCP Server

Contents

• Quick start

• How it works

• Prerequisites

• Installation

• The API key

• Configuration

• Delegation modes

• Choosing a model

• Costs

• Tool reference

• Operating it

• Job artifacts

• Troubleshooting

• Platform support

• Security model

• Development

How it works

OpenRouter exposes an Anthropic-compatible POST /v1/messages endpoint alongside its OpenAI-shaped one, so Claude Code talks to it unmodified when pointed at the right base URL. Each delegated task runs as claude -p in its own process with:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<your OpenRouter key>
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<small model>
ANTHROPIC_SMALL_FAST_MODEL=<small model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>
ANTHROPIC_CUSTOM_HEADERS=HTTP-Referer: …⏎X-Title: …
CLAUDE_CODE_MAX_OUTPUT_TOKENS=<clamped per model>

The base URL stops at /api because Claude Code appends /v1/messages itself. ANTHROPIC_AUTH_TOKEN is used rather than ANTHROPIC_API_KEY because it is sent as Authorization: Bearer <key>, which is the scheme OpenRouter expects.

The child environment is built from a small per-platform allowlist. Anything matching ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_* or OPENROUTER_* is dropped before the OpenRouter values are applied. That last prefix is deliberate: the delegate needs the key only as ANTHROPIC_AUTH_TOKEN, so it never receives a second copy under a name that other tooling it runs might pick up.

Delegates also start with --strict-mcp-config and no MCP config, which keeps their startup fast and stops them from recursively calling this server.

Two details that are not optional

Output-token clamping. Claude Code asks for max_tokens: 32000 on every request. Plenty of OpenRouter models cap lower — amazon/nova-micro-v1 allows 5120 — and reject the request outright. The server reads top_provider.max_completion_tokens from the catalog and pins CLAUDE_CODE_MAX_OUTPUT_TOKENS to what the chosen model actually accepts.

Tool-calling is mandatory. Claude Code sends a ~110 KB body with a full tool schema on every request. A model that cannot call tools fails on turn one, after you have paid for it. The server refuses such models up front using the catalog's supported_parameters.

Prerequisites

node --version
claude --version
curl -s -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/credits      # {"data":{"total_credits":…}}

Installation

From npm (recommended)

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  -- npx -y claude-openrouter-delegate-mcp

Or install it globally, which also puts the settings CLI on your PATH:

npm install -g claude-openrouter-delegate-mcp
openrouter-mcp-config --api-key sk-or-v1-...
claude mcp add openrouter --scope user -- claude-openrouter-delegate-mcp

From source

git clone https://github.com/histonedev/claude-openrouter-delegate-mcp.git
cd claude-openrouter-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add openrouter --scope user -- node "$(pwd)/dist/index.js"

Run the settings CLI as node dist/cli.js …, or npm link to get openrouter-mcp-config on your PATH.

Confirm

claude mcp list        # openrouter: ... - ✔ Connected

Then restart your Claude Code session — the tool list is read at startup.

The API key

Resolved from the first of these that is set:

1. OPENROUTER_API_KEY (highest — the name the rest of the ecosystem uses)

2. OPENROUTER_MCP_API_KEY

3. apiKeyFile in a config file — a path to a file containing the key

4. apiKey in a config file

openrouter-mcp-config --api-key sk-or-v1-...        # writes ~/.openrouter-mcp/config.json, mode 0600
openrouter-mcp-config --api-key-file ~/.secrets/or  # or keep it somewhere else entirely

The key is never exposed through an MCP tool. openrouter_models reports it as sk-or-v1-a...7f2e, the CLI prints the same masked form, and the config file is written 0600. A key passed with --api-key --scope project is redirected to the user config, because project configs get committed.

If you would rather have no key on disk at all, pin it on the MCP registration with --env OPENROUTER_API_KEY=… and skip the config file.

Configuration

Settings resolve from four layers, later winning over earlier:

1. built-in defaults

2. user config — ~/.openrouter-mcp/config.json (override with $OPENROUTER_MCP_CONFIG)

3. project config — ./openrouter-mcp.config.json in the server's working directory

4. environment variables

{
  "delegationMode": "ondemand",
  "defaultModel": "deepseek/deepseek-v4-flash-0731",
  "smallModel": "google/gemini-3.7-flash",
  "allowedModels": ["deepseek/deepseek-v4-flash-0731", "qwen/qwen3.7-flash"],
  "defaultPermissionMode": "auto",
  "maxOutputTokens": 16000,
  "requireToolSupport": true
}

Changing settings

Settings are changed from a terminal, never by the model:

openrouter-mcp-config                                   # show current settings + active layers
openrouter-mcp-config --mode auto                       # off | ondemand | auto
openrouter-mcp-config --default-model qwen/qwen3.7-flash
openrouter-mcp-config --small-model google/gemini-3.7-flash
openrouter-mcp-config --allow deepseek/deepseek-v4-flash-0731,qwen/qwen3.7-flash
openrouter-mcp-config --permission-mode acceptEdits
openrouter-mcp-config --scope project                   # write ./openrouter-mcp.config.json

Then restart your Claude Code session so the server re-reads its config.

There is deliberately no MCP tool for this. See Security model.

Delegation modes

This controls how eagerly the orchestrator reaches for delegation, by rewriting the tool descriptions the model actually reads. Changing it requires a session restart, by design.

Both modes carry an explicit cost warning, because unlike a local model every delegated turn is billed and every request carries tens of thousands of input tokens.

Choosing a model

OpenRouter serves 400+ models. openrouter_models filters to tool-capable ones and truncates by default, since dumping the whole catalog into the orchestrator's context is expensive in itself.

openrouter_models({ filter: "gemini", limit: 10 })
openrouter_models({ free_only: true })

The default is deepseek/deepseek-v4-flash-0731: tool-capable, 1.3M context, and cheap. Set allowedModels to pin delegation to a shortlist you trust — the allowed set is embedded in the delegate_start description, so the orchestrator knows the menu without an extra call, and any other model is rejected by name rather than silently substituted.

Model quality varies, and that is your problem to manage

These are not Claude models, and Claude Code leans on the model harder than a chat UI does. Observed while building this package, on real runs:

• A model may call its tools correctly and then return no final text. The work happened; the closing message did not. The server detects this and hands back the recorded activity trail instead of an empty result.

• A model may emit its own native tool-call markup as plain text — DeepSeek producing <｜DSML｜tool_calls> inside a reasoning block — instead of a structured tool call. Nothing executes and the tokens are still billed. Longer and more convoluted prompts make this more likely.

• The tool calls: 0 annotation on a finished job is there for the classic failure: a confident answer about your repository that no tool call backs.

Prefer short, single-purpose prompts for weaker models, cap work with max_turns, and check delegate_status when a claim matters.

Costs

Every finished job reports a cost, and the label tells you how much to trust it:

cost:       $0.00045   (billed by OpenRouter, 1 generation(s))
cost:       >=$0.00045 (billed so far -- 1 of 2 generations recorded)
cost:       $0.00924   (rough list-price estimate; actual routing may differ several-fold)

OpenRouter возвращает свой идентификатор генерации как идентификатор сообщения Anthropic, поэтому сервер собирает их и запрашивает /v1/generation, чтобы узнать, сколько на самом деле стоила каждая генерация. Это авторитетное число. Записи о списаниях появляются через мгновение после завершения генерации, поэтому задача может кратко показывать частичную сумму — она отображается как >=, но никогда как итоговая цифра, потому что единственное направление, в котором отображение стоимости не должно ошибаться, — это вниз.

Оценка — это запасной вариант, когда запись не удаётся получить. Относитесь к ней только как к порядку величины: при тестировании одинаковые количества токенов на одной и той же модели выставлялись в счёт в десять раз по-разному в зависимости от маршрутизации провайдера и попаданий в кэш, а арифметика по прейскуранту в одном прогоне оказалась завышенной в 20 раз.

Две вещи, которые стоит знать о подсчёте токенов:

• Claude Code сообщает почти весь промпт как cache_creation_input_tokens, а не input_tokens. Строка tokens: in … суммирует все классы входных токенов. Задача, которая выглядит как «12 входных токенов», на самом деле — ~42 000.

• OpenRouter маршрутизирует к провайдерам, которые часто не соблюдают кэш (native_tokens_cached: 0), поэтому возобновлённый разговор не так дёшев, как предполагают цифры чтения из кэша.

Сокращаем счёт. smallModel — самый мощный рычаг: слот haiku в Claude Code обслуживает фоновые служебные вызовы, и направить его на что-то дешёвое, пока основная модель остаётся способной, почти ничего не стоит по качеству. После этого: max_turns ограничивает агентный цикл, а allowed_tools не даёт делегату исследовать больше репозитория, чем нужно для задачи.

Справочник по инструментам

delegate_start

delegate_followup принимает job_id или session_id, а также ту же пару prompt/prompt_file и необязательные permission_mode, max_turns, wait_seconds.

Эксплуатация

Асинхронность по умолчанию

delegate_start возвращает job_id за миллисекунды; делегат продолжает работать в фоне. Это не даёт длинной задаче заблокировать вашу сессию или сорвать таймаут MCP-клиента — большинство клиентов отказываются от одного запроса через 60 секунд, а это меньше, чем занимают многие делегированные задачи.

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

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

Двусторонние разговоры

Каждая задача несёт session_id. Передача её job_id в delegate_followup возобновляет сессию с полной историей; session_id остаётся стабильным между ходами, тогда как каждый ход получает свежий job_id.

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

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

Длинные промпты

У каждого параметра промпта есть аналог prompt_file. Внутренне промпт всегда записывается на диск и подаётся в CLI через stdin — никогда как элемент argv и никогда через оболочку. Обратные кавычки, $(...), кавычки, переводы строк и символы глобов проходят без изменений, и нет ограничения на длину argv.

Разрешения

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

Отмена

delegate_cancel({ job_id: "A" })

Убивает делегата и всё, что он запустил, и останавливает дальнейшее списание кредитов. Сервер также убивает работающих делегатов при завершении работы.

Артефакты задач

Каждая задача пишет в ~/.openrouter-mcp/jobs/<job_id>/:

stream.jsonl — это то, куда стоит смотреть, когда сводка делегата неубедительна: там хранятся фактические результаты инструментов, а не пересказ модели. Ничего не удаляется автоматически — удалите каталог, когда захотите.

Устранение неполадок

No OpenRouter API key configured Задайте OPENROUTER_API_KEY или выполните openrouter-mcp-config --api-key sk-or-v1-..., затем перезапустите сессию.

OpenRouter rejected the API key (HTTP 401) Проверьте ключ на openrouter.ai/keys. Обратите внимание, что ключ считывается при запуске сервера, поэтому для нового ключа нужен перезапуск сессии.

Model "x" does not support tool calling Работает как задумано — Claude Code отправляет схему инструментов в каждом запросе. Выберите другую модель или задайте requireToolSupport: false, чтобы попробовать в любом случае.

Model "x" is not in the allowed list Работает как задумано. Выполните openrouter-mcp-config --allow <models>, затем перезапустите.

Делегат не возвращает текст, или его вызовы инструментов ничего не делают Это проблема качества модели, а не подключения — см. Качество моделей различается. Попробуйте более короткий промпт или более сильную модель и прочитайте stream.jsonl, чтобы увидеть, что произошло на самом деле.

Request timed out от вашего MCP-клиента wait_seconds превысил таймаут запроса клиента (часто 60 с). Уберите его и опрашивайте через delegate_status — именно для этого и задумана асинхронная архитектура.

HTTP 400 про max_tokens Потолок вывода модели ниже запрошенного. Сервер автоматически ограничивает значение по каталогу; если каталог неверен, уменьшите maxOutputTokens.

Инструменты не появляются в Claude Code Список инструментов считывается при запуске сессии. Перезапустите или проверьте claude mcp list.

Делегат мгновенно падает с ошибкой запуска CLI не найден. Задайте OPENROUTER_MCP_CLAUDE_BIN как абсолютный путь к claude.

Поддержка платформ

Различия платформ изолированы в src/platform.ts:

Разрешение бинарника. На POSIX spawn ищет в PATH. На Windows нативная установка даёт claude.exe, а установка через npm даёт claude.cmd, который CreateProcess не может выполнить напрямую — поэтому сервер проходит по PATH × PATHEXT, предпочитая .exe, и в крайнем случае маршрутизирует обёртку .cmd через cmd.exe.

Экранирование аргументов. Этот запасной вариант применяет два слоя: квотирование argv по MSVCRT, затем экранирование служебных символов cmd кареткой (& | < > ^ " ( ) % !). Пропуск второго слоя — это классическая дыра для внедрения команд в .cmd. Промпты никогда не касаются этого пути — они идут через stdin. Одно ограничение: многострочный append_system_prompt не может пересечь командную строку cmd.exe, поэтому сервер выдаёт понятную ошибку, указывающую на OPENROUTER_MCP_CLAUDE_BIN, вместо того чтобы молча исказить его.

Разрешительный список окружения. Windows сохраняет гораздо больший набор, чем POSIX. SystemRoot и windir не являются необязательными — удалите их, и Winsock не сможет инициализироваться, так что дочерний процесс вообще не сможет открыть сокет.

Отмена. Дочерние процессы POSIX порождаются detached как лидеры групп процессов и отменяются через process.kill(-pid); Windows использует taskkill /T /F.

Модель безопасности

Изоляция учётных данных — это суть. Окружение дочернего процесса строится с нуля, а не наследуется, и переменные провайдера удаляются до применения значений OpenRouter. test/env-unit.mjs проверяет, что ключ достигает дочернего процесса ровно в одной переменной и что ни один родительский секрет не выживает; test/e2e.mjs отравляет родителя поддельным ANTHROPIC_API_KEY и настоящим ANTHROPIC_BASE_URL=https://api.anthropic.com и подтверждает, что делегат не видит ни того, ни другого.

Ключ никогда не читается через инструмент. Каждый диагностический путь маскирует его, и test/readonly.mjs проверяет, что ни вывод инструментов, ни вывод CLI не содержат ключ. Здесь это важнее, чем в родственном проекте для Ollama, где токен — это буквальная строка ollama.

Политика делегирования не доступна для записи модели. Нет MCP-инструмента для изменения delegationMode, allowedModels или ключа API. Модель, которой неудобен режим ondemand, не может переключить себя на auto и начать тратить. Настройки загружаются один раз при запуске, никогда не изменяются во время выполнения, и в описаниях инструментов указано, что политика не входит в полномочия модели.

Это ограждение, а не граница безопасности. Агент с доступом к оболочке может по-прежнему редактировать файл конфигурации. Что даёт удаление инструмента — так это то, что такое изменение становится видимым редактированием файла, которое вступает в силу только при следующем перезапуске, а не одним тихим вызовом инструмента посреди задачи. Чтобы сделать это герметичным, закрепите значения через --env при регистрации MCP, что переопределяет файлы конфигурации:

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  --env OPENROUTER_MCP_DELEGATION_MODE=ondemand \
  --env OPENROUTER_MCP_ALLOWED_MODELS=deepseek/deepseek-v4-flash-0731 \
  -- node /path/to/claude-openrouter-delegate-mcp/dist/index.js

Расходы реальны. Вышедший из-под контроля оркестратор в режиме auto тратит ваши кредиты, а не ваше терпение. Установите лимит ключа OpenRouter на ключе, который вы даёте этому серверу — это потолок, с которым модель не может спорить.

Делегаты наследуют вашу файловую систему. Они работают от вашего имени пользователя в cwd, который вы им даёте, с defaultPermissionMode. Относитесь к делегированной сессии так же, как к любой сессии Claude Code — используйте disallowed_tools или режим разрешений «только чтение», когда поручаете работу модели, которой доверяете меньше.

Разработка

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

Тесты

node test/env-unit.mjs       # env isolation, key handling, model slot wiring
node test/pricing-unit.mjs   # cost arithmetic, catalog filtering, URL normalisation
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination (cross-platform)
OPENROUTER_API_KEY=... node test/e2e.mjs     # full MCP round trip         (costs ~$0.01)
OPENROUTER_API_KEY=... node test/async.mjs   # async polling, prompt_file, cancel
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test запускает четыре теста, которым не нужна сеть. Они проходят как в Windows, так и в POSIX — тест дерева процессов строит своё дерево из процессов node, а не из встроенных команд оболочки, поэтому он не привязан только к POSIX.

Публикация релиза

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

Запускайте npm publish из настоящего терминала, а не из скрипта или неинтерактивной оболочки. При 2FA через WebAuthn/security-ключ CLI проходит проверку, открывая браузер; без TTY он не может этого сделать и вместо этого требует TOTP-код, который security-ключ не может сгенерировать (npm error code EOTP). Для CI вместо этого используйте гранулярный токен доступа с правом Bypass 2FA.

Пакет поставляется только с dist/, README.md и LICENSE. publishConfig.access имеет значение public, а prepare запускает tsc перед упаковкой, поэтому устаревший dist/ никогда не будет опубликован.

Структура

Лицензия

MIT — см. LICENSE.