claude-openrouter-delegate-mcp

Delega tareas de una sesión de Claude Code respaldada por Anthropic a sesiones de Claude Code respaldadas por OpenRouter, sin que ambas compartan variables de entorno.

Apuntar Claude Code a OpenRouter implica exportar variables ANTHROPIC_* a tu shell. Esas variables son a nivel de proceso, así que un shell es o "Anthropic" o "OpenRouter", nunca ambos — y un ANTHROPIC_AUTH_TOKEN exportado con tu clave de OpenRouter está a un subproceso descuidado de filtrarse.

Este servidor MCP lanza cada sesión delegada como un proceso hijo con un entorno construido explícitamente. Tu sesión Opus conserva sus propias credenciales; el delegado recibe las de OpenRouter. Se ejecutan lado a lado en la misma 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

Este es un hermano de claude-ollama-delegate-mcp, que hace lo mismo para un servidor Ollama local. La diferencia que lo condiciona todo aquí: OpenRouter cuesta dinero real y ofrece más de 400 modelos, así que este paquete añade una ruta de clave de API, un catálogo de modelos con precios y un informe de coste por trabajo.

Inicio rápido

# 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

Luego pide la delegación en lenguaje natural:

delega esto a openrouter: resume cada símbolo exportado en src/

Por defecto el servidor solo delega cuando lo pides explícitamente. Para que el orquestador decida por sí mismo, consulta Modos de delegación.

Related MCP server: Ollama MCP Server

Contenido

• Inicio rápido

• Cómo funciona

• Requisitos previos

• Instalación

• La clave de API

• Configuración

• Modos de delegación

• Elegir un modelo

• Costes

• Referencia de herramientas

• Operación

• Artefactos de trabajo

• Solución de problemas

• Soporte de plataformas

• Modelo de seguridad

• Desarrollo

Cómo funciona

OpenRouter expone un endpoint POST /v1/messages compatible con Anthropic junto al suyo con forma de OpenAI, así que Claude Code habla con él sin modificaciones cuando se apunta a la URL base correcta. Cada tarea delegada se ejecuta como claude -p en su propio proceso con:

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>

La URL base termina en /api porque Claude Code añade /v1/messages por su cuenta. Se usa ANTHROPIC_AUTH_TOKEN en lugar de ANTHROPIC_API_KEY porque se envía como Authorization: Bearer <key>, que es el esquema que OpenRouter espera.

El entorno hijo se construye a partir de una pequeña lista de permitidos por plataforma. Cualquier cosa que coincida con ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_* u OPENROUTER_* se descarta antes de aplicar los valores de OpenRouter. Ese último prefijo es deliberado: el delegado necesita la clave solo como ANTHROPIC_AUTH_TOKEN, así que nunca recibe una segunda copia bajo un nombre que otras herramientas que ejecute podrían captar.

Los delegados también arrancan con --strict-mcp-config y sin configuración MCP, lo que mantiene su arranque rápido y evita que llamen recursivamente a este servidor.

Dos detalles que no son opcionales

Limitación de tokens de salida. Claude Code pide max_tokens: 32000 en cada petición. Muchos modelos de OpenRouter tienen un tope inferior — amazon/nova-micro-v1 permite 5120 — y rechazan la petición directamente. El servidor lee top_provider.max_completion_tokens del catálogo y fija CLAUDE_CODE_MAX_OUTPUT_TOKENS a lo que el modelo elegido acepta realmente.

La llamada a herramientas es obligatoria. Claude Code envía un cuerpo de ~110 KB con un esquema completo de herramientas en cada petición. Un modelo que no puede llamar a herramientas falla en el primer turno, después de que hayas pagado por él. El servidor rechaza esos modelos de antemano usando el supported_parameters del catálogo.

Requisitos previos

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

Instalación

Desde npm (recomendado)

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

O instálalo globalmente, lo que también pone el CLI de ajustes en tu 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

Desde el código fuente

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"

Ejecuta el CLI de ajustes como node dist/cli.js …, o usa npm link para tener openrouter-mcp-config en tu PATH.

Confirmación

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

Luego reinicia tu sesión de Claude Code — la lista de herramientas se lee al arrancar.

La clave de API

Se resuelve de la primera de estas que esté definida:

1. OPENROUTER_API_KEY (la más alta — el nombre que usa el resto del ecosistema)

2. OPENROUTER_MCP_API_KEY

3. apiKeyFile en un archivo de configuración — una ruta a un archivo que contiene la clave

4. apiKey en un archivo de configuración

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

La clave nunca se expone a través de una herramienta MCP. openrouter_models la reporta como sk-or-v1-a...7f2e, el CLI imprime la misma forma enmascarada y el archivo de configuración se escribe con permisos 0600. Una clave pasada con --api-key --scope project se redirige a la configuración de usuario, porque las configuraciones de proyecto se acaban commitando.

Si prefieres no tener ninguna clave en disco, fíjala en el registro MCP con --env OPENROUTER_API_KEY=… y omite el archivo de configuración.

Configuración

Los ajustes se resuelven desde cuatro capas, ganando las posteriores sobre las anteriores:

1. valores por defecto integrados

2. configuración de usuario — ~/.openrouter-mcp/config.json (anulable con $OPENROUTER_MCP_CONFIG)

3. configuración de proyecto — ./openrouter-mcp.config.json en el directorio de trabajo del servidor

4. variables de entorno

{
  "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
}

Cambiar los ajustes

Los ajustes se cambian desde una terminal, nunca por el modelo:

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

Luego reinicia tu sesión de Claude Code para que el servidor relea su configuración.

Deliberadamente no hay ninguna herramienta MCP para esto. Consulta el Modelo de seguridad.

Modos de delegación

Esto controla con qué entusiasmo el orquestador recurre a la delegación, reescribiendo las descripciones de herramientas que el modelo lee realmente. Cambiarlo requiere reiniciar la sesión, por diseño.

Ambos modos llevan una advertencia de coste explícita, porque a diferencia de un modelo local cada turno delegado se factura y cada petición lleva decenas de miles de tokens de entrada.

Elegir un modelo

OpenRouter sirve más de 400 modelos. openrouter_models filtra a los capaces de usar herramientas y trunca por defecto, ya que volcar todo el catálogo en el contexto del orquestador es caro en sí mismo.

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

El valor por defecto es deepseek/deepseek-v4-flash-0731: capaz de usar herramientas, 1,3M de contexto y barato. Define allowedModels para fijar la delegación a una lista corta de tu confianza — el conjunto permitido está incrustado en la descripción de delegate_start, así que el orquestador conoce el menú sin una llamada extra, y cualquier otro modelo se rechaza por nombre en lugar de sustituirse silenciosamente.

La calidad de los modelos varía, y eso es problema tuyo

No son modelos Claude, y Claude Code se apoya en el modelo más que una interfaz de chat. Observado mientras se construía este paquete, en ejecuciones reales:

• Un modelo puede llamar a sus herramientas correctamente y luego no devolver ningún texto final. El trabajo ocurrió; el mensaje de cierre no. El servidor lo detecta y devuelve el rastro de actividad registrado en lugar de un resultado vacío.

• Un modelo puede emitir su propio marcado nativo de llamada a herramientas como texto plano — DeepSeek produciendo <｜DSML｜tool_calls> dentro de un bloque de razonamiento — en lugar de una llamada a herramienta estructurada. Nada se ejecuta y los tokens se facturan igualmente. Los prompts más largos y enrevesados hacen esto más probable.

• La anotación tool calls: 0 en un trabajo terminado está ahí para el fallo clásico: una respuesta segura sobre tu repositorio que ninguna llamada a herramienta respalda.

Prefiere prompts cortos y de un solo propósito para modelos más débiles, limita el trabajo con max_turns y comprueba delegate_status cuando una afirmación importe.

Costes

Cada trabajo terminado reporta un coste, y la etiqueta te dice cuánto puedes fiarte de él:

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 devuelve su id de generación como el id de mensaje de Anthropic, así que el servidor los recopila y pregunta a /v1/generation cuánto costó realmente cada solicitud. Ese es el número autoritativo. Los registros de facturación llegan un momento después de que la generación termina, así que un trabajo puede informar brevemente una suma parcial — mostrada como >=, nunca como cifra final, porque la única dirección en la que una visualización de coste no debe equivocarse es hacia abajo.

La estimación es el recurso de respaldo cuando no se puede obtener un registro. Trátala solo como un orden de magnitud: en las pruebas, recuentos de tokens idénticos en el mismo modelo se facturaron diez veces diferentes según el enrutamiento del proveedor y los aciertos de caché, y la aritmética del precio de lista salió 20× alta en una ejecución.

Dos cosas que vale la pena saber sobre los recuentos de tokens:

• Claude Code informa casi todo el prompt como cache_creation_input_tokens, no como input_tokens. La línea tokens: in … suma todas las clases de entrada. Un trabajo que parece "12 tokens de entrada" en realidad son ~42.000.

• OpenRouter enruta a proveedores que a menudo no respetan la caché (native_tokens_cached: 0), así que una conversación reanudada no es tan barata como sugieren las cifras de lectura de caché.

Reduciendo la factura. smallModel es la palanca más potente: el hueco de haiku de Claude Code atiende llamadas de utilidad en segundo plano, y apuntarlo a algo barato mientras el modelo principal sigue siendo capaz apenas cuesta nada en calidad. Después: max_turns limita un bucle agéntico, y allowed_tools impide que un delegado explore más del repositorio de lo que la tarea necesita.

Referencia de herramientas

delegate_start

delegate_followup acepta job_id o session_id, además del mismo par prompt/prompt_file y permission_mode, max_turns, wait_seconds opcionales.

Cómo operarlo

Asíncrono por defecto

delegate_start devuelve un job_id en milisegundos; el delegado sigue ejecutándose en segundo plano. Esto evita que una tarea larga bloquee tu sesión o haga saltar el tiempo de espera de un cliente MCP — la mayoría de los clientes abandonan una única solicitud después de 60 segundos, que es menos de lo que tardan muchas tareas delegadas.

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

Pasa wait_seconds en cualquiera de esas para bloquear en su lugar — útil para tareas cortas, pero mantenlo por debajo del tiempo de espera de solicitud de tu cliente.

Conversaciones bidireccionales

Cada trabajo lleva un session_id. Pasar su job_id a delegate_followup reanuda la sesión con el historial completo; el session_id permanece estable entre turnos mientras que cada turno recibe un job_id nuevo.

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)

Reanudar reproduce la conversación como tokens de entrada, así que un hilo largo cuesta más por turno que uno nuevo — pero sigue siendo mucho menos que reconstruir el mismo contexto.

Prompts largos

Cada parámetro de prompt tiene su contraparte prompt_file. Internamente el prompt siempre se escribe en disco y se alimenta a la CLI a través de stdin — nunca como entrada de argv y nunca a través de un shell. Las comillas invertidas, $(...), las comillas, los saltos de línea y los caracteres glob pasan tal cual, y no hay límite de longitud de argv.

Permisos

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

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

Cancelación

delegate_cancel({ job_id: "A" })

Mata al delegado y todo lo que haya iniciado, y detiene que gaste más créditos. El servidor también mata a los delegados en ejecución cuando se apaga.

Artefactos del trabajo

Cada trabajo escribe en ~/.openrouter-mcp/jobs/<job_id>/:

stream.jsonl es donde mirar cuando el resumen de un delegado no resulta convincente: contiene los resultados reales de las herramientas, no el relato del modelo sobre ellos. Nada se poda automáticamente — borra el directorio cuando quieras.

Solución de problemas

No OpenRouter API key configured Establece OPENROUTER_API_KEY, o openrouter-mcp-config --api-key sk-or-v1-..., y luego reinicia la sesión.

OpenRouter rejected the API key (HTTP 401) Compruébala en openrouter.ai/keys. Ten en cuenta que la clave se lee al iniciar el servidor, así que una clave nueva requiere reiniciar la sesión.

Model "x" does not support tool calling Funciona como se espera — Claude Code envía un esquema de herramientas en cada solicitud. Elige otro modelo, o establece requireToolSupport: false para intentarlo de todos modos.

Model "x" is not in the allowed list Funciona como se espera. Ejecuta openrouter-mcp-config --allow <models> y luego reinicia.

El delegado no devuelve texto, o sus llamadas a herramientas no hacen nada Es un problema de calidad del modelo, no de conexión — consulta La calidad del modelo varía. Prueba con un prompt más corto o un modelo más potente, y lee stream.jsonl para ver qué ocurrió realmente.

Request timed out desde tu cliente MCP wait_seconds superó el tiempo de espera por solicitud del cliente (a menudo 60s). Elimínalo y consulta con delegate_status en su lugar — para eso está el diseño asíncrono.

HTTP 400 sobre max_tokens El límite de salida del modelo está por debajo de lo solicitado. El servidor lo ajusta automáticamente al valor del catálogo; si el catálogo es incorrecto, baja maxOutputTokens.

Las herramientas no aparecen en Claude Code La lista de herramientas se lee al inicio de la sesión. Reinicia, o comprueba claude mcp list.

El delegado falla al instante con un error de lanzamiento No se encontró la CLI. Establece OPENROUTER_MCP_CLAUDE_BIN a la ruta absoluta de claude.

Soporte de plataformas

Las diferencias de plataforma están aisladas en src/platform.ts:

Resolución del binario. En POSIX, spawn busca en PATH. En Windows, una instalación nativa da claude.exe mientras que una instalación npm da claude.cmd, que CreateProcess no puede ejecutar directamente — así que el servidor recorre PATH × PATHEXT prefiriendo .exe, y recurre a enrutar un shim .cmd a través de cmd.exe.

Escapado de argumentos. Ese recurso aplica dos capas: el entrecomillado de argv de MSVCRT, y luego un escape con intercalación de los metacaracteres propios de cmd (& | < > ^ " ( ) % !). Omitir la segunda capa es el clásico agujero de inyección de comandos en .cmd. Los prompts nunca tocan esta ruta — viajan por stdin. Una limitación: un append_system_prompt multilínea no puede cruzar una línea de comandos de cmd.exe, así que el servidor lanza un error claro que apunta a OPENROUTER_MCP_CLAUDE_BIN en lugar de alterarlo silenciosamente.

Lista de permitidos del entorno. Windows conserva un conjunto mucho mayor que POSIX. SystemRoot y windir no son opcionales — si se eliminan, Winsock no consigue inicializarse, así que el hijo no puede abrir un socket en absoluto.

Cancelación. Los hijos POSIX se lanzan detached como líderes de grupo de procesos y se cancelan con process.kill(-pid); Windows usa taskkill /T /F.

Modelo de seguridad

El aislamiento de credenciales es el punto. El entorno del hijo se construye desde cero en lugar de heredarse, y las variables del proveedor se eliminan antes de aplicar los valores de OpenRouter. test/env-unit.mjs verifica que la clave llega al hijo en exactamente una variable y que ningún secreto del padre sobrevive; test/e2e.mjs envenena al padre con una ANTHROPIC_API_KEY falsa y una ANTHROPIC_BASE_URL=https://api.anthropic.com real y confirma que el delegado no ve ninguna de las dos.

La clave nunca es legible a través de una herramienta. Cada ruta de diagnóstico la enmascara, y test/readonly.mjs verifica que ninguna salida de herramienta y ninguna salida de CLI contenga la clave. Esto importa más aquí que en el hermano de Ollama, donde el token es la cadena literal ollama.

La política de delegación no es modificable por el modelo. No hay ninguna herramienta MCP para cambiar delegationMode, allowedModels o la clave de API. Un modelo que encuentre ondemand inconveniente no puede cambiarse a sí mismo a auto y empezar a gastar. Los ajustes se cargan una vez al inicio, nunca se mutan en tiempo de ejecución, y las descripciones de las herramientas indican que la política no es algo que el modelo pueda cambiar.

Esto es una barrera de protección, no un límite de seguridad. Un agente con acceso al shell aún puede editar el archivo de configuración. Lo que te aporta eliminar la herramienta es que tal cambio sea una edición de archivo visible que solo surte efecto en el siguiente reinicio, en lugar de una única llamada a herramienta silenciosa a mitad de tarea. Para hacerlo hermético, fija los valores mediante --env en el registro MCP, que sobrescribe los archivos de configuración:

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

El gasto es real. Un orquestador desbocado en modo auto gasta tus créditos, no tu paciencia. Mantén un límite de clave de OpenRouter en la clave que le des a este servidor — ese es un techo con el que el modelo no puede discutir.

Los delegados heredan tu sistema de archivos. Se ejecutan como tu usuario en el cwd que les des, con defaultPermissionMode. Trata una sesión delegada como tratarías cualquier sesión de Claude Code — usa disallowed_tools o un modo de permisos de solo lectura cuando entregues trabajo a un modelo en el que confíes menos.

Desarrollo

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

Pruebas

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 ejecuta las cuatro que no necesitan red. Pasan tanto en Windows como en POSIX: la prueba de árbol de procesos construye su árbol con procesos de node en lugar de elementos integrados del shell, por lo que no es exclusiva de POSIX.

Publicación de una versión

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

Ejecuta npm publish desde una terminal real, no desde un script ni un shell no interactivo. Con WebAuthn/llave de seguridad 2FA la CLI completa el desafío abriendo un navegador; sin un TTY no puede, y recurre a exigir un código TOTP que una llave de seguridad no puede producir (npm error code EOTP). Para CI, usa un token de acceso granular con Bypass 2FA en su lugar.

El paquete incluye solo dist/, README.md y LICENSE. publishConfig.access es public, y prepare ejecuta tsc antes del empaquetado, por lo que un dist/ obsoleto nunca puede publicarse.

Estructura

Licencia

MIT — consulta LICENSE.