ollama-mcp
ollama-mcp
将基于 Anthropic 的 Claude Code 会话中的任务委派给 基于 Ollama 的 Claude Code 会话——且两者永不共享环境变量。
ollama launch claude --model <model> 通过将 ANTHROPIC_* 变量导出到你的 shell 中工作。这就是它通常需要单独终端的原因:变量是进程范围内的,因此一个 shell 要么是“Anthropic”要么是“Ollama”,永远不能同时是两者。
此 MCP 服务器将每个委派会话作为子进程生成,并带有显式构建的环境。你的 Opus 会话保留自己的凭据和模型设置;委派者获得 Ollama 的。它们在同一终端中并行运行。
┌────────────────────────────┐
│ 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-cloud目录
Related MCP server: opencode-bridge
工作原理
Ollama 的服务器暴露了一个兼容 Anthropic 的 POST /v1/messages 端点,因此 Claude Code 可以在指向正确的基础 URL 后未经修改地与它通信。每个委派任务作为 claude -p 在其自己的进程中运行,并带有:
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>所有三个模型槽位指向同一个 Ollama 模型,以便别名(opus、sonnet、haiku)以及在委派者内部生成的任何子代理都解析到该模型,而不是静默回退到 Anthropic 的默认值。
子环境是从一个小的、按平台划分的允许列表中构建的。任何匹配 ANTHROPIC_*、CLAUDE_*、AWS_*、GOOGLE_*、AZURE_*、OPENAI_*、BEDROCK_*、VERTEX_* 的内容都会在应用 Ollama 值之前被丢弃,因此你 shell 中残留的 ANTHROPIC_API_KEY 无法泄露到(或计费给)委派运行。
委派者还以 --strict-mcp-config 启动,并且没有 MCP 配置,这可以保持其快速启动,并阻止它们递归调用此服务器。
前提条件
要求 | 说明 |
Node.js 20+ |
|
Ollama | ollama.com/download。必须正在运行: |
Claude Code CLI | claude.com/code。 |
至少一个模型 |
|
一个 Ollama 账户 | 仅适用于 |
在安装前验证各个组件:
node --version # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version # {"version":"..."}
ollama list # at least one model云端模型 vs 本地模型。 标记为
:cloud的模型在 Ollama 的基础设施上运行,需要ollama signin;它们比大多数笔记本电脑内存所能容纳的模型强大得多,这使得它们成为委派的实际选择。本地模型同样有效,且永远不会离开你的机器。
安装
从 npm 安装(推荐)
无需克隆或构建——npx 按需获取:
claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcp或者全局安装,这也会将设置 CLI 放入你的 PATH:
npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcp从源码安装
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"以 node dist/cli.js … 运行设置 CLI,或运行 npm link 将 ollama-mcp-config 放入你的 PATH。
作用域
--scope user 使其在每个项目中可用;--scope project 将其写入当前仓库的 .mcp.json 并与协作者共享;--scope local 将其保留在此机器和此项目中。
确认
claude mcp list # ollama: ... - ✔ Connected然后重新启动你的 Claude Code 会话——工具列表在启动时读取。
配置
设置从四个层级解析,后者的优先级更高:
内置默认值
用户配置——
~/.ollama-mcp/config.json(使用$OLLAMA_MCP_CONFIG覆盖路径)项目配置——服务器工作目录中的
./ollama-mcp.config.json环境变量
{
"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
}设置 | 环境变量 | 默认值 | 含义 |
|
|
| 委派使用的积极性——见下文 |
|
|
| 委派可以使用的模型 |
|
| 第一个允许的云端模型 | 当调用省略模型时使用的默认模型 |
|
|
| 委派者的权限模式 |
|
|
| Ollama 端点 |
|
|
| Claude Code CLI 的路径 |
|
|
| 提示、转录、结果 |
|
|
| 单轮对话的硬超时时间 |
|
|
| 输出超过此长度将被截断;完整文本在磁盘上 |
更改设置
设置从终端更改,绝不能由模型更改:
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.json然后重新启动你的 Claude Code 会话,以便服务器重新读取其配置。
这里故意没有 MCP 工具。 参见安全模型。
允许的模型
allowedModels: [](默认值)允许服务器提供的任何模型。如果列表非空:
delegate_start会拒绝列表之外的模型,并指出允许的集合,而不是静默替换ollama_models会将排除的模型标记为BLOCKED by allowedModels允许的列表嵌入在
delegate_start工具描述中,因此编排器无需额外调用即可知道可用选项CLI 拒绝会将
defaultModel置于新列表之外的更改
委派模式
这控制编排器有多积极地寻求委派,通过重写模型实际读取的工具描述。更改它需要重新启动会话,这是有意设计的。
模式 | 效果 |
|
|
| 仅在你明确要求时委派——“委派这个”、“使用 ollama”、“询问 qwen”。否则编排器自己完成工作,不提及这些工具。 |
| 编排器自行决定,使用描述中内置的标准。 |
在 auto 模式下,描述告诉编排器将那些自包含、易于验证且消耗大量上下文的工作委派出去——批量文件摘要、初步搜索、机械性重构、样板代码和测试脚手架、日志或差异分类——而将架构决策、安全敏感变更、模糊需求和最终审查留给自己。它还被告知要验证委派的结果,原因见操作指南。
工具参考
工具 | 用途 |
| 列出可服务的模型并报告当前设置(只读) |
| 启动任务;立即返回 |
| 向同一会话发送另一条消息 |
| 轮询状态以及委派者工具调用的尾部信息 |
| 收集最终输出 |
| 终止正在运行的委派者及其启动的所有内容 |
| 列出任务,按对话分组 |
delegate_start
参数 | 类型 | 说明 |
| string | 任务。与 |
| string | 包含提示的文件的路径。内容较长时优先使用。 |
| string | 必须在允许列表中。默认为 |
| string | 委派者的工作目录。默认为服务器的工作目录。 |
| enum |
|
| string([] | 例如 |
| string([] | 例如 |
| string | 委派者的额外指令 |
| number | 限制委派者的代理轮次 |
| string([] | 额外可访问的目录 |
| number | 最多阻塞 N 秒(0–600)。默认 0 = 立即返回。 |
delegate_followup 接受 job_id 或 session_id,加上相同的 prompt/prompt_file 对以及可选的 permission_mode、max_turns、wait_seconds。
操作指南
默认异步
delegate_start 在毫秒级返回 job_id;委派者在后台继续运行。这可以防止长时间任务阻塞你的会话或触发 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 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 变体。在内部,提示总是被写入磁盘,并通过 stdin 传递给 CLI——绝不会作为 argv 条目传入,也不会通过 shell 传递。反引号、$(...)、引号、换行符和通配符字符会原样传递,且没有 argv 长度限制。
delegate_start({ prompt_file: "/tmp/refactor-brief.md" })权限
委托默认使用 defaultPermissionMode(auto)。缩小特定调用的范围:
// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })
// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })信任委托的输出
每个完成的结果都会报告其工具调用次数。较弱的模型有时会自信地给出答案而不实际运行任何操作——在开发过程中,一个模型曾声称某个环境变量未设置,但从未调用过 Bash;在被推动后,它运行了命令并报告了正确的值。
带有 tool calls: 0 的结果因此被标记为未验证:
tool calls: 0 <- answered without using any tools; treat factual claims as unverifieddelegate_status 显示实际的跟踪信息。纯粹的对话式后续交互合法地为零次调用——该标志意味着“没有东西支持这个结果”,而不是“出了什么问题”。
取消
delegate_cancel({ job_id: "A" })杀死委托及其启动的所有进程,因此正在执行长时间构建的委托不会让构建继续运行。
作业工件
每个作业写入 ~/.ollama-mcp/jobs/<job_id>/:
文件 | 内容 |
| 实际发送的内容 |
| 完整的 |
| 元数据:状态、模型、令牌数、计时、退出代码 |
| 最终输出文本 |
超过 maxInlineChars 的结果会在工具响应中被截断,完整文本可从 result.txt 读取。不会自动修剪任何内容——你可以随时删除该目录。
故障排除
Cannot reach Ollama at http://127.0.0.1:11434
Ollama 未运行。启动 ollama serve 或打开桌面应用程序。如果它监听在其他地址,请设置 OLLAMA_MCP_BASE_URL。
No models available from Ollama
运行 ollama pull qwen3.5:397b-cloud,并针对 :cloud 模型运行 ollama signin。
<model> was retired at …(HTTP 410)
Ollama 已移除该云端模型。ollama list 仍会显示已淘汰模型的本地缓存清单——请检查实际可用的模型并更新 defaultModel。
Model "x" is not in the allowed list
按预期工作。运行 ollama-mcp-config --allow <models>,然后重启。
工具在 Claude Code 中不显示
工具列表在会话启动时读取。重启,或检查 claude mcp list。
委托立即失败并显示启动错误
未找到 CLI。将 OLLAMA_MCP_CLAUDE_BIN 设置为 claude 的绝对路径。
一切都很慢
云端模型每次交互都需要一次往返,而 Claude Code 在每个请求中都会发送一个大型系统提示(约 25k 令牌)。使用 max_turns 限制代理循环,使用 allowed_tools 阻止委托探索超出必要范围。
平台支持
平台 | 状态 |
macOS | 已端到端测试 |
Linux | 支持;与 macOS 使用相同的 POSIX 代码路径 |
Windows | 设计上支持,尚未在真实硬件上测试 |
平台差异在 src/platform.ts 中隔离:
二进制解析。 在 POSIX 上,spawn 会搜索 PATH。在 Windows 上,原生安装提供 claude.exe,而 npm 安装提供 claude.cmd,CreateProcess 无法直接执行后者——因此服务器会遍历 PATH × PATHEXT,优先选择 .exe,并退回通过 cmd.exe 路由 .cmd 包装器。
参数转义。 这种回退方案应用了两层:MSVCRT argv 引用,然后对 cmd 自身的元字符(& | < > ^ " ( ) % !)进行脱字符转义。跳过第二层是经典的 .cmd 命令注入漏洞。提示永远不会经过此路径——它们通过 stdin 传输。一个限制是:多行的 append_system_prompt 不能跨越 cmd.exe 命令行,因此服务器会抛出一个清晰的错误,指向 OLLAMA_MCP_CLAUDE_BIN,而不是静默地破坏它。
环境允许列表。 Windows 保留的环境变量集比 POSIX 大得多。SystemRoot 和 windir 不是可选的——移除它们会导致 Winsock 初始化失败,因此子进程即使连接到 localhost 也无法打开套接字。名称匹配时不区分大小写,但复制时使用父进程的原始拼写。
取消。 POSIX 子进程以 detached 方式生成,作为进程组领导者,并通过 process.kill(-pid) 取消;Windows 使用 taskkill /T /F。无论哪种方式,委托自身的子进程都会随之终止。服务器在关闭时也会杀死正在运行的委托。
安全模型
凭据隔离是核心要点。 子环境从头构建,而不是继承,并且在应用 Ollama 值之前会剥离提供者变量。这一点在 test/env-unit.mjs 中有所涵盖,而 test/e2e.mjs 会在父进程中注入一个假的 ANTHROPIC_API_KEY,并断言它永远不会到达委托。
委托策略不可由模型写入。 没有 MCP 工具可以更改 delegationMode 或 allowedModels。早期版本中曾有一个,那是一个错误:一个发现 ondemand 不方便的模型可以在一次调用中将其切换到 auto,然后自由委托。现在设置仅在启动时加载一次,运行时永远不被修改,并且工具描述中说明策略不是模型可以更改的。
这是一个护栏,不是安全边界。 具有 shell 访问权限的代理仍然可以编辑配置文件。移除该工具的意义在于,这样的更改将是一个可见的文件编辑,并且仅在下次重启时生效,而不是在任务中间进行一次静默的单一工具调用。要使其无懈可击,请在 MCP 注册时通过 --env 固定这些值,这会覆盖配置文件:
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.js委托继承你的文件系统。 它们以你的用户身份在你指定的 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: 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 运行三个不需要网络的测试。
发布版本
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该包是 claude-ollama-delegate-mcp,仅发布 dist/、README.md 和 LICENSE。publishConfig.access 为 public,prepare 在打包前运行 tsc,因此永远不会发布过时的 dist/。在发布前使用 npm pack --dry-run 预览 tarball。
布局
文件 | 责任 |
| MCP 服务器、工具注册和处理器 |
| 分层配置加载和验证 |
| 启动时解析的设置单例 |
| 模式相关的工具描述 |
| 子环境构建和提供者变量阻止列表 |
| Windows/POSIX 生成、参数转义、进程树杀死 |
| 作业生命周期、 |
| 模型发现和允许列表强制执行 |
|
|
许可证
MIT——参见 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