ollama-mcp
ollama-mcp
Delegar tareas desde una sesión de Claude Code respaldada por Anthropic a sesiones de Claude Code respaldadas por Ollama — sin que las dos compartan nunca variables de entorno.
ollama launch claude --model <model> funciona exportando variables ANTHROPIC_* a tu shell. Por eso normalmente necesita su propio terminal: las variables son a nivel de proceso, por lo que un shell es o bien "Anthropic" o bien "Ollama", nunca ambos.
Este servidor MCP genera cada sesión delegada como un proceso hijo con un entorno explícitamente construido. Tu sesión Opus conserva sus propias credenciales y ajustes de modelo; el delegado recibe los de Ollama. Se ejecutan en paralelo en el mismo terminal.
┌────────────────────────────┐
│ Claude Code (Opus) │ your session, Anthropic credentials
│ │
│ └─ mcp: ollama-mcp ──────┼──▶ spawn: claude -p (fresh env)
└────────────────────────────┘ ANTHROPIC_BASE_URL=127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
→ qwen3.5:397b-cloudContenido
Related MCP server: opencode-bridge
Cómo funciona
El servidor de Ollama expone un endpoint compatible con Anthropic POST /v1/messages, por lo que Claude Code puede comunicarse con él sin modificaciones si se apunta a la URL base correcta. Cada tarea delegada se ejecuta como claude -p en su propio proceso con:
ANTHROPIC_BASE_URL=http://127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>Los tres espacios de modelo apuntan al mismo modelo de Ollama para que los alias (opus, sonnet, haiku) y cualquier subagente generado dentro del delegado se resuelvan a él, en lugar de caer silenciosamente en un valor predeterminado de Anthropic.
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_* se elimina antes de aplicar los valores de Ollama, por lo que una ANTHROPIC_API_KEY suelta en tu shell no puede filtrarse a — ni facturarse en — una ejecución delegada.
Los delegados también se inician con --strict-mcp-config y sin configuración de MCP, lo que mantiene su inicio rápido y evita que llamen recursivamente a este servidor.
Requisitos previos
Requisito | Notas |
Node.js 20+ |
|
Ollama | ollama.com/download. Debe estar en ejecución: |
CLI de Claude Code | claude.com/code. |
Al menos un modelo |
|
Una cuenta de Ollama | Solo para modelos |
Verifica las piezas antes de instalar:
node --version # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version # {"version":"..."}
ollama list # at least one modelModelos cloud vs. locales. Los modelos etiquetados
:cloudse ejecutan en la infraestructura de Ollama y requierenollama signin; son mucho más capaces que lo que la mayoría de portátiles caben en memoria, lo que los convierte en la opción práctica para delegación. Los modelos locales también funcionan y nunca abandonan tu máquina.
Instalación
Desde npm (recomendado)
No se necesita clonar ni compilar — npx lo obtiene bajo demanda:
claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcpO instálalo globalmente, lo que también pone el CLI de configuración en tu PATH:
npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcpDesde fuente
git clone https://github.com/histonedev/claude-ollama-delegate-mcp.git
cd claude-ollama-delegate-mcp
npm install # builds automatically via the prepare script
claude mcp add ollama --scope user -- node "$(pwd)/dist/index.js"Ejecuta el CLI de configuración como node dist/cli.js …, o npm link para tener ollama-mcp-config en tu PATH.
Ámbitos
--scope user lo hace disponible en todos los proyectos; --scope project escribe en .mcp.json en el repositorio actual y lo comparte con colaboradores; --scope local lo mantiene solo para esta máquina y proyecto.
Confirmar
claude mcp list # ollama: ... - ✔ ConnectedLuego reinicia tu sesión de Claude Code — la lista de herramientas se lee al inicio.
Configuración
La configuración se resuelve desde cuatro capas, ganando la última sobre la anterior:
valores predeterminados internos
configuración de usuario —
~/.ollama-mcp/config.json(sobrescribe la ruta con$OLLAMA_MCP_CONFIG)configuración de proyecto —
./ollama-mcp.config.jsonen el directorio de trabajo del servidorvariables de entorno
{
"delegationMode": "ondemand",
"allowedModels": ["qwen3.5:397b-cloud", "gemma4:31b-cloud"],
"defaultModel": "qwen3.5:397b-cloud",
"defaultPermissionMode": "auto",
"baseUrl": "http://127.0.0.1:11434",
"claudeBin": "claude",
"stateDir": "~/.ollama-mcp/jobs",
"jobTimeoutMs": 1800000,
"maxInlineChars": 60000
}Ajuste | Variable de entorno | Valor predeterminado | Significado |
|
|
| Con qué entusiasmo se usa la delegación — ver abajo |
|
|
| Modelos que la delegación puede usar |
|
| primer modelo cloud permitido | Modelo cuando una llamada lo omite |
|
|
| Modo de permisos para delegados |
|
|
| Endpoint de Ollama |
|
|
| Ruta al CLI de Claude Code |
|
|
| Prompts, transcripciones, resultados |
|
|
| Corte forzoso para un turno |
|
|
| Salida por encima de esto se trunca; texto completo en disco |
Cambiar la configuración
La configuración se cambia desde un terminal, nunca por el modelo:
ollama-mcp-config # show current settings + active layers
ollama-mcp-config --mode auto # off | ondemand | auto
ollama-mcp-config --allow qwen3.5:397b-cloud # or: --allow all
ollama-mcp-config --default-model qwen3.5:397b-cloud
ollama-mcp-config --permission-mode acceptEdits
ollama-mcp-config --scope project # write ./ollama-mcp.config.jsonLuego reinicia tu sesión de Claude Code para que el servidor relea su configuración.
No hay intencionadamente una herramienta MCP para esto. Ver Modelo de seguridad.
Modelos permitidos
allowedModels: [] (el valor predeterminado) permite cualquier modelo que ofrezca el servidor. Con una lista no vacía:
delegate_startrechaza un modelo fuera de ella, nombrando el conjunto permitido en lugar de sustituir uno silenciosamenteollama_modelsmarca los modelos excluidos comoBLOQUEADO por allowedModelsla lista permitida está incrustada en la descripción de la herramienta
delegate_start, para que el orquestador conozca el menú sin una llamada extrael CLI rechaza un cambio que dejaría
defaultModelfuera de la nueva lista
Modos de delegación
Esto controla con qué entusiasmo el orquestador recurre a la delegación, reescribiendo las descripciones de herramientas que el modelo realmente lee. Cambiarlo requiere reiniciar la sesión, por diseño.
Modo | Efecto |
| Las herramientas |
| Delegar solo cuando lo pidas explícitamente — "delega esto", "usa ollama", "pregunta a qwen". De lo contrario, el orquestador hace el trabajo él mismo y no menciona las herramientas. |
| El orquestador decide por sí mismo, usando criterios integrados en la descripción. |
En modo auto la descripción le indica al orquestador que delegue trabajo que sea autocontenido, fácilmente verificable y que consuma mucho contexto — resumen masivo de archivos, búsquedas de primer paso, refactorizaciones mecánicas, código repetitivo y andamios de pruebas, triaje de registros o diffs — mientras que mantiene para sí mismo las decisiones de arquitectura, cambios sensibles a la seguridad, requisitos ambiguos y la revisión final. También se le indica que verifique las afirmaciones delegadas, por la razón en Operación.
Referencia de herramientas
Herramienta | Propósito |
| Listar modelos servibles e informar ajustes actuales (solo lectura) |
| Iniciar una tarea; devuelve un |
| Enviar otro mensaje a la misma sesión |
| Consultar estado más un extracto de las llamadas a herramientas del delegado |
| Recoger la salida final |
| Terminar un delegado en ejecución y todo lo que haya iniciado |
| Listar trabajos, agrupados por conversación |
delegate_start
Parámetro | Tipo | Notas |
| string | La tarea. Mutuamente excluyente con |
| string | Ruta a un archivo que contiene el prompt. Preferido cuando es largo. |
| string | Debe estar en la lista de permitidos. Predeterminado: |
| string | Directorio de trabajo para el delegado. Predeterminado: el cwd del servidor. |
| enum |
|
| string. | p.ej. |
| string. | p.ej. |
| string | Instrucciones extra para el delegado |
| number | Limitar los turnos agénticos del delegado |
| string. | Directorios accesibles adicionales |
| number | Bloquear hasta N segundos (0–600). Predeterminado 0 = devolver inmediatamente. |
delegate_followup toma job_id o session_id, más el mismo par prompt/prompt_file y permission_mode, max_turns, wait_seconds opcionales.
Operación
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 detenga tu sesión o provoque un tiempo de espera del cliente MCP.
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 textPasa wait_seconds en cualquiera de esos para bloquear en su lugar — útil para tareas cortas donde no vale la pena una ida y vuelta de sondeo.
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 cada turno obtiene un nuevo 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)El seguimiento es mucho más barato que empezar de nuevo cuando el delegado ya tiene el contexto relevante cargado.
Prompts largos
Cada parámetro de prompt tiene su contraparte prompt_file. Internamente, el prompt siempre se escribe en disco y se envía a la CLI a través de stdin — nunca como entrada argv ni a través de un shell. Las comillas invertidas, $(...), las comillas, los saltos de línea y los caracteres glob se transmiten literalmente, y no hay límite de longitud de argv.
delegate_start({ prompt_file: "/tmp/refactor-brief.md" })Permisos
Los delegados usan por defecto defaultPermissionMode (auto). Restringe una llamada específica:
// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })
// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })Confiar en la salida delegada
Cada resultado finalizado informa su recuento de llamadas a herramientas. Los modelos más débiles a veces responden con confianza sin ejecutar nada — durante el desarrollo, un modelo afirmó que una variable de entorno no estaba configurada sin invocar Bash; al ser presionado, ejecutó el comando e informó el valor correcto.
Un resultado con tool calls: 0 se anota, por tanto, como no verificado:
tool calls: 0 <- answered without using any tools; treat factual claims as unverifieddelegate_status muestra el rastro real. Una respuesta puramente conversacional legítimamente tiene cero — la marca significa "esto no está respaldado por nada", no "algo se rompió".
Cancelación
delegate_cancel({ job_id: "A" })Mata al delegado y todo lo que inició, por lo que un delegado que estuviera a medio camino de una compilación larga no deja la compilación ejecutándose.
Artefactos de trabajo
Cada trabajo escribe en ~/.ollama-mcp/jobs/<job_id>/:
Archivo | Contenido |
| Exactamente lo que se envió |
| Transcripción completa de |
| Metadatos: estado, modelo, tokens, tiempos, código de salida |
| Texto de salida final |
Los resultados más largos que maxInlineChars se truncan en la respuesta de la herramienta y el texto completo se lee de result.txt. No se elimina nada automáticamente — elimina el directorio cuando quieras.
Solución de problemas
Cannot reach Ollama at http://127.0.0.1:11434
Ollama no se está ejecutando. Inicia ollama serve o abre la aplicación de escritorio. Si escucha en otro lugar, establece OLLAMA_MCP_BASE_URL.
No models available from Ollama
ollama pull qwen3.5:397b-cloud, y ollama signin para modelos :cloud.
<model> was retired at … (HTTP 410)
Ollama eliminó ese modelo en la nube. ollama list aún muestra manifiestos almacenados en caché localmente para modelos retirados — comprueba qué funciona realmente y actualiza defaultModel.
Model "x" is not in the allowed list
Funciona según lo previsto. ollama-mcp-config --allow <models>, luego reinicia.
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 instantáneamente con un error de inicio
No se encontró la CLI. Establece OLLAMA_MCP_CLAUDE_BIN en la ruta absoluta de claude.
Todo es lento
Los modelos en la nube pagan un viaje de ida y vuelta por turno, y Claude Code envía un prompt de sistema grande (~25k tokens) en cada solicitud. Usa max_turns para limitar los bucles agentivos y allowed_tools para evitar que el delegado explore más de lo necesario.
Soporte de plataforma
Plataforma | Estado |
macOS | Probado de extremo a extremo |
Linux | Compatible; misma ruta de código POSIX que macOS |
Windows | Compatible por diseño, aún no probado en hardware real |
Las diferencias de plataforma están aisladas en src/platform.ts:
Resolución binaria. 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 — por lo que el servidor recorre PATH × PATHEXT prefiriendo .exe, y recurre a enrutar un shim .cmd a través de cmd.exe.
Escapado de argumentos. Esa alternativa aplica dos capas: el citado argv de MSVCRT, luego un escapado con caret de los propios metacaracteres de cmd (& | < > ^ " ( ) % !). Omitir la segunda capa es el clásico agujero de inyección de comandos .cmd. Los prompts nunca tocan esta ruta — viajan por stdin. Una limitación: un append_system_prompt de múltiples líneas no puede cruzar una línea de comandos de cmd.exe, por lo que el servidor genera un error claro señalando OLLAMA_MCP_CLAUDE_BIN en lugar de mutilarlo silenciosamente.
Lista blanca de entorno. Windows conserva un conjunto mucho más grande que POSIX. SystemRoot y windir no son opcionales — elimínalos y Winsock falla al inicializarse, por lo que el hijo no puede abrir un socket ni siquiera para localhost. Los nombres se comparan sin distinción de mayúsculas y minúsculas, pero se copian con la ortografía original del padre.
Cancelación. Los hijos de POSIX se generan detached como líderes de grupo de procesos y se cancelan con process.kill(-pid); Windows usa taskkill /T /F. De cualquier manera, los propios subprocesos del delegado mueren con él. El servidor también mata a los delegados en ejecución cuando se apaga.
Modelo de seguridad
El aislamiento de credenciales es el punto. El entorno hijo se construye desde cero en lugar de heredarse, y las variables del proveedor se eliminan antes de aplicar los valores de Ollama. Esto está cubierto por test/env-unit.mjs, y test/e2e.mjs envenena al padre con una ANTHROPIC_API_KEY falsa y afirma que nunca llega al delegado.
La política de delegación no puede ser escrita por el modelo. No hay ninguna herramienta MCP para cambiar delegationMode o allowedModels. Una versión anterior tenía una, que fue un error: un modelo que encuentra inconveniente ondemand podría cambiarse a auto en una sola llamada y luego delegar libremente. La configuración ahora se carga una vez al inicio, nunca se muta en tiempo de ejecución, y las descripciones de las herramientas indican que la política no puede ser cambiada por el modelo.
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 compra eliminar la herramienta es que tal cambio es una edición de archivo visible que solo surte efecto en el próximo reinicio, en lugar de una única llamada silenciosa a la herramienta en medio de una tarea. Para hacerlo hermético, fija los valores a través de --env en el registro MCP, que anula los archivos de configuración:
claude mcp add ollama --scope user \
--env OLLAMA_MCP_DELEGATION_MODE=ondemand \
--env OLLAMA_MCP_ALLOWED_MODELS=qwen3.5:397b-cloud \
-- node /path/to/claude-ollama-delegate-mcp/dist/index.jsLos 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 lo harías con cualquier sesión de Claude Code — usa disallowed_tools o un modo de permiso de solo lectura al asignar trabajo a un modelo en el que confíes menos.
Desarrollo
npm install # installs and builds
npm run build # tsc
npm run dev # tsc --watchPruebas
node test/env-unit.mjs # env isolation: no secret leaks, platform vars present
node test/quoting.mjs # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs # process-tree termination
node test/e2e.mjs # full MCP round trip (needs Ollama running)
node test/async.mjs # async polling, prompt_file, cancel (needs Ollama)
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs # config is read-only to the modelnpm test ejecuta las tres que no necesitan red.
Publicar un lanzamiento
npm login # interactive, once per machine
npm version patch # or minor / major -- tags and bumps
npm publish # prepare script builds first
git push --follow-tagsEl paquete es claude-ollama-delegate-mcp y envía solo dist/, README.md y LICENSE. publishConfig.access es public, y prepare ejecuta tsc antes de empaquetar, por lo que nunca se puede publicar un dist/ obsoleto. Previsualiza el tarball con npm pack --dry-run antes de enviar.
Diseño
Archivo | Responsabilidad |
| Servidor MCP, registro de herramientas y manejadores |
| Carga y validación de configuración en capas |
| Singleton de configuración resuelta al inicio |
| Descripciones de herramientas dependientes del modo |
| Construcción del entorno hijo y lista de bloqueo de variables del proveedor |
| Spawn en Windows/POSIX, escapado de argumentos, matar árbol de procesos |
| Ciclo de vida del trabajo, análisis de |
| Descubrimiento de modelos y aplicación de lista blanca |
| CLI de configuración |
Licencia
MIT — consulta LICENSE.
Available Tools
7 toolsdelegate_cancelCancel a delegated taskA
Terminate a running delegated Ollama session and everything it started.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job_id to cancel. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add one key behavioral trait: that cancellation terminates 'everything it started,' indicating cascading termination. However, it omits details like whether the operation is destructive (assumed but not stated), whether it requires any permissions, or what the return behavior is (e.g., blocking, asynchronous).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, with the core verb 'Terminate' front-loaded. Every word adds value, and there is no fluff or redundancy. It is as concise as possible while still conveying the key behavioral nuance of cascade cancellation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally adequate. It specifies what it terminates and the scope, but does not cover important usage context such as error cases (e.g., cancelling a non-existent session), whether it is safe for any session, or what the result looks like. Some additional detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'job_id' with a clear description. The tool description adds no further semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'terminate a running delegated Ollama session and everything it started,' which specifies the action (terminate), the resource (delegated Ollama session), and an important scope ('everything it started'). This distinguishes it from sibling tools like delegate_start and delegate_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for canceling a running session but provides no explicit guidance on when to use versus alternatives (e.g., delegate_status to check status first) or when not to use (e.g., if the session is already completed). It lacks any before/after context or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delegate_followupContinue a delegated conversationA
Send another message to an existing delegated session, resuming its full conversation history. Identify it by job_id (any turn) or session_id. Returns a new job_id for this turn while keeping the same session_id, so you can go back and forth with the Ollama model.
Only continue conversations the user asked you to start.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | A job_id from any earlier turn of the conversation. | |
| prompt | No | The next message. Use prompt_file for long prompts. | |
| max_turns | No | Cap the delegate's agentic turns for this turn. | |
| session_id | No | The Claude Code session id, as an alternative to job_id. | |
| prompt_file | No | Path to a file holding the next message. | |
| wait_seconds | No | Block up to this many seconds before returning. | |
| permission_mode | No | Override the permission mode for this turn. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that a new job_id is returned for this turn while the session_id remains the same, enabling back-and-forth interaction. Without annotations, the description carries the burden; it could mention any blocking behavior or side effects, but the transparency is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with the core action, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 parameters, full schema coverage, no output schema, and no annotations, the description explains the essential behavior and identification methods. It could be more complete by noting the default behavior for optional parameters like max_turns or wait_seconds, but is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions job_id and session_id as alternatives for identification but does not add new semantic meaning beyond the schema for other parameters. It doesn't go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends another message to an existing delegated session, resuming conversation history. It distinguishes itself from siblings like delegate_start by focusing on continuation, and the title reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (continue a delegated conversation) and includes exclusion guidance: 'Only continue conversations the user asked you to start.' This clearly differentiates from delegate_start and sets a boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delegate_listList delegated tasksC
Show delegated jobs from this server's lifetime, newest first, grouped by conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum jobs to list. Default 20. | |
| state | No | Filter by state. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses ordering and grouping, but does not state whether the tool is read-only, has performance implications, or returns partial results. The lack of mutation or safety context is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that includes key details (ordering, grouping). No wasted words, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lists delegated jobs from a server's lifetime with no output schema. The description is sparse: it does not explain what fields are returned, pagination behavior, or how grouping works. More context is needed for an agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are clear for both parameters, so the baseline is 3. However, the description adds no extra meaning beyond what the schema already provides (e.g., does not explain what 'state' values mean in context, how limit interacts with grouping, or defaults).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists delegated jobs, specifying order (newest first) and grouping (by conversation). It distinguishes from siblings like delegate_status or delegate_result, but could be more explicit about what 'delegated jobs' refers to in context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings such as delegate_status or delegate_cancel. The description does not mention prerequisites, typical use cases, or when not to use it, leaving the agent to infer based on name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delegate_resultGet a delegated task's outputA
Return the final text produced by a delegated Ollama session, plus its session_id for follow-ups. Blocks until the job finishes if you pass wait_seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job_id to collect. | |
| wait_seconds | No | Block up to this many seconds for the job to finish. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool blocks if wait_seconds is provided, and returns both the text and session_id. It does not discuss potential side effects, rate limits, or what happens if the job fails, but the blocking behavior is the key transparent element.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and every sentence adds value. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters, no output schema, and no nested objects, so its simplicity reduces the required completeness. The description adequately covers the inputs and the blocking behavior. It could mention what happens if the job hasn't started yet or if it fails, but given the low complexity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'job_id' is the collected delegation identifier and that 'wait_seconds' controls blocking up to a maximum. This clarifies the semantics beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('final text...plus session_id'), clarifying the precise output. It distinguishes itself from sibling tools like 'delegate_status' (which likely returns status only) and 'delegate_start' (which starts work).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (after a delegation is created, to get final output) and mentions the optional wait_seconds for blocking behavior. However, it does not explicitly contrast with 'delegate_followup' or 'delegate_status'—though the context signals suggest those exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delegate_startDelegate a task to an Ollama modelA
Start a headless Claude Code session backed by an Ollama model and return immediately with a job_id. It runs in its own process with its own environment, so your Anthropic credentials and model settings are untouched. Poll with delegate_status, collect with delegate_result, and continue the conversation with delegate_followup. Pass prompt_file for long prompts.
WHEN TO USE — ON EXPLICIT REQUEST ONLY. Delegation mode is "ondemand". Call this only when the user actually asks for it: "delegate this", "use ollama", "ask qwen", "run this on a local model", or when they name an Ollama model. If the user has not asked for delegation, do the work yourself and do not offer this tool unprompted.
This policy is set by the user and is not yours to change. If it is getting in the way, say so and let the user run ollama-mcp-config; do not edit config files to widen it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for the delegated session. Defaults to the server's cwd. | |
| model | No | Ollama model id. Must be in the allowed list. Defaults to the configured default. | |
| prompt | No | The task for the Ollama-backed session. Use prompt_file for long prompts. | |
| add_dirs | No | Additional directories the delegate may access. | |
| max_turns | No | Cap the delegate's agentic turns. | |
| prompt_file | No | Path to a file holding the prompt. Preferred for long or special-character-heavy prompts. | |
| wait_seconds | No | Block up to this many seconds for completion. Default 0. | |
| allowed_tools | No | Tool allowlist, e.g. ['Read','Grep','Bash(git *)']. | |
| permission_mode | No | Permission mode for the delegate. Defaults to the configured default. | |
| disallowed_tools | No | Tool denylist, e.g. ['Write','Edit']. | |
| append_system_prompt | No | Extra instructions appended to the delegate's system prompt. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses key behaviors: the tool runs in its own process with its own environment, so the user's Anthropic credentials and model settings are untouched. It also mentions that delegation mode is 'ondemand.' However, it does not detail what happens upon failure (e.g., if the Ollama model is unavailable) or the format of the returned job_id, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear first paragraph about the tool's function and a separate 'WHEN TO USE' section. It is front-loaded with the core purpose. However, the second paragraph could be slightly more concise—it repeats the 'ON EXPLICIT REQUEST ONLY' instruction—and the policy enforcement sentence adds redundancy. Still, it is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema, the description provides sufficient context: it explains the async nature, mentions sibling tools for follow-up, and includes usage boundaries. Some details about parameter interplay (e.g., wait_seconds vs. polling with delegate_status) or return value format are missing, but the description is functionally complete for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions using `prompt_file` for long prompts and lists a few sibling tools for polling/collection. It does not elaborate on parameter constraints or relationships (e.g., mutual exclusivity of prompt and prompt_file).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Start a headless Claude Code session backed by an Ollama model and return immediately with a job_id.' It identifies the resource (delegate session) and the action (start). It also distinguishes itself from siblings by mentioning polling with delegate_status, collecting with delegate_result, and continuing with delegate_followup, making differentiation clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use instructions: 'ON EXPLICIT REQUEST ONLY' and lists triggering phrases like 'delegate this', 'use ollama', 'ask qwen', etc. It also states when not to use: 'If the user has not asked for delegation, do the work yourself and do not offer this tool unprompted.' This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delegate_statusCheck a delegated taskA
Report whether a delegated job is still running, plus a tail of what the Ollama session has been doing — its actual tool calls and partial text. Optionally block until it finishes. Use the tool-call trace to check that a delegate really did the work it claims.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job_id returned by delegate_start or delegate_followup. | |
| wait_seconds | No | Block up to this many seconds waiting for completion. | |
| progress_limit | No | How many recent activity lines to show. Default 15. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It transparently discloses the tool's behavior: it reports running status, provides a tail of activity (including tool calls and partial text), and can optionally block for a specified duration. It does not mention potential side effects, but since it's a read-only monitoring operation, the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. The second sentence adds a usage tip, which is relevant but slightly redundant. Every sentence earns its place, and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are 3 parameters, no output schema, and no annotations, the description is reasonably complete. It explains the tool's purpose, the key output (status and trace), and the optional blocking feature. It lacks explicit mention of the return format or error cases, but for a monitoring tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description in the schema. The description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool reports the status of a delegated job ('Report whether a delegated job is still running'), a tail of activity ('actual tool calls and partial text'), and the option to block until completion. This distinguishes it from siblings like delegate_start (which initiates a job) and delegate_result (which presumably gets the final result).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context for when to use this tool: to check if a delegate is still running and to use the tool-call trace to verify a delegate's actions. It does not explicitly state when not to use it or name alternatives, but the context ('Use the tool-call trace to check that a delegate really did the work it claims') implies it is for post-delegation monitoring versus delegate_cancel for aborting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ollama_modelsList Ollama modelsA
List the Ollama models available for delegation, the current delegation mode and allowed-model policy, and the environment variables a delegated session receives. Use this to pick a model, or to report the current configuration when the user asks about it.
These settings are user-controlled. There is no tool to change them: if the user wants a different delegation mode or model policy, tell them to run ollama-mcp-config in a terminal and restart the session. Do not edit the config files yourself.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states that the tool lists models, delegation mode, policy, and env vars, and that settings are user-controlled. It also warns that there is no tool to change them and instructs the agent not to edit config files. This covers the read-only nature and constraints. However, it does not mention any potential side effects, error conditions, or details about the output format, which would have made it a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, tightly packed with information. The first sentence gives the purpose, the second gives usage guidance, and the last two provide behavioral context and alternative actions. No redundant sentences or filler. It is well-structured and front-loaded, making it easy for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description provides a solid overview of what the tool returns and how to use it. However, it lacks a brief description of the output format (e.g., whether it returns a list of model names or a structured JSON). This is a minor gap, but overall the description is sufficient for the agent to understand the tool's purpose and constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (no parameters to describe). According to the guidelines, this gives a baseline of 4. The description does not add parameter semantics because there are none, and it correctly avoids adding unnecessary info. The score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'List' and clearly identifies the resources: Ollama models, delegation mode, allowed-model policy, and environment variables. It distinguishes from sibling tools which are about delegation actions (start, cancel, followup, etc.) by focusing on listing models and configuration. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this to pick a model, or to report the current configuration when the user asks about it.' It also provides crucial guidance on what not to do: there is no tool to change settings, and the agent should tell the user to run 'ollama-mcp-config' in a terminal and restart the session, and not to edit config files. This is exceptional for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v1.0.0- First observed
delegate_cancel - First observed
delegate_followup - First observed
delegate_list - First observed
delegate_result - First observed
delegate_start - First observed
delegate_status - First observed
ollama_models
TDQS
Scored across 7 tools
Each tool targets a distinct lifecycle stage of a delegated Ollama session (start, status, result, followup, cancel, list). However, `delegate_cancel` and `delegate_result` have similar purposes (termination vs. final output), which could cause minor confusion but descriptions clarify the difference.
All tool names follow a consistent `delegate_<verb>` pattern (cancel, list, start, followup, status, result). The naming is clear, predictable, and uses only snake_case.
With 7 tools, the set is well-scoped for managing delegated sessions. Each tool has a clear role with no unnecessary extras, covering creation, polling, output retrieval, continuation, cancellation, and listing.
The tool surface covers the full lifecycle of a delegated session: start, poll status, get final result, follow up, cancel, list active/historical jobs, and even inspect the model configuration (`ollama_models`). No obvious gaps for the intended purpose.
Maintenance
Related MCP Connectors
Delegate tasks between AI agents on different platforms and collect the results.
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Stop copy-pasting between Claude Chat and Claude Code.
Related MCP Servers
- AlicenseAqualityCmaintenanceDelegate tasks from Claude Code to other models (Codex CLI, DeepSeek, OpenRouter, etc.) without leaving the app.221MIT
- AlicenseAqualityCmaintenanceLets Claude Code delegate coding tasks to external models running on a local opencode serve, preserving main agent tokens for planning and review.828 npm1MIT
- AlicenseBqualityAmaintenanceBridges Claude with a local Ollama coding model, letting Claude delegate bounded implementation tasks to the local model while retaining reasoning, review, and safety enforcement.122,285 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code and Cursor to delegate tasks to each other, spreading workload across both AI coding subscriptions.15 npmMIT