This server lets you delegate coding tasks from your main Claude Code session to isolated, Ollama-backed Claude Code subprocesses without mixing credentials.
List Ollama models and report configuration — ollama_models shows servable models, delegation mode, allowed-model policy, and the environment delegates receive.
Start delegated tasks — delegate_start launches a headless claude -p session against Ollama with a prompt or prompt file, chosen model, working directory, permission mode, allowed/disallowed tools, extra system prompt, turn cap, and optional blocking wait; returns a job_id immediately.
Continue conversations — delegate_followup resumes an existing delegated session (by job or session id) with full history.
Check progress — delegate_status shows whether a job is running plus a tail of the delegate's actual tool calls, so you can verify claims.
Collect output — delegate_result returns the final text, session id, and metadata; long output is truncated inline but saved fully to disk.
Cancel jobs — delegate_cancel kills a running delegate and everything it spawned.
List jobs — delegate_list shows jobs grouped by conversation, filtered by state.
Persist artifacts — every job stores its prompt, full transcript, metadata, and result text under ~/.ollama-mcp/jobs/<job_id>/.
Integrates with Ollama's API by configuring Claude Code delegates to use Ollama's Anthropic-compatible endpoint, enabling task execution using Ollama models (local or cloud).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ollama-mcp Could you delegate this code review to qwen3.5?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Delegate tasks from an Anthropic-backed Claude Code session to Ollama-backed Claude Code sessions — without the two ever sharing environment variables.
ollama launch claude --model <model> works by exporting ANTHROPIC_* variables
into your shell. That is why it normally needs its own terminal: the variables
are process-wide, so one shell is either "Anthropic" or "Ollama", never both.
This MCP server spawns each delegated session as a child process with an explicitly constructed environment. Your Opus session keeps its own credentials and model settings; the delegate gets Ollama's. They run side by side in the same terminal.
┌────────────────────────────┐
│ Claude Code (Opus) │ your session, Anthropic credentials
│ │
│ └─ mcp: ollama ──────────┼──▶ spawn: claude -p (fresh env)
└────────────────────────────┘ ANTHROPIC_BASE_URL=127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
→ qwen3.5:397b-cloud# 1. Ollama running, Claude Code installed, at least one model pulled
ollama pull qwen3.5:397b-cloud
# 2. register the server
claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcp
# 3. restart your Claude Code sessionThen ask for delegation in plain language:
delegate this to ollama: summarise every exported symbol in src/
By default the server only delegates when you explicitly ask. To let the orchestrator decide for itself, see Delegation modes.
Related MCP server: codex-as-mcp
Ollama's server exposes an Anthropic-compatible POST /v1/messages endpoint, so
Claude Code can talk to it unmodified if pointed at the right base URL. Each
delegated task runs as claude -p in its own process with:
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>All three model slots point at the same Ollama model so that aliases (opus,
sonnet, haiku) and any subagent spawned inside the delegate resolve to it,
rather than silently falling back to an Anthropic default.
The child environment is built from a small per-platform allowlist. Anything
matching ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*,
BEDROCK_*, VERTEX_* is dropped before the Ollama values are applied, so a
stray ANTHROPIC_API_KEY in your shell cannot leak into — or bill — a delegated
run.
Delegates also start with --strict-mcp-config and no MCP config, which keeps
their startup fast and stops them from recursively calling this server.
Requirement | Notes |
Node.js 20+ |
|
Ollama | ollama.com/download. Must be running: |
Claude Code CLI | claude.com/code. |
At least one model |
|
An Ollama account | Only for |
Verify the pieces before installing:
node --version # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version # {"version":"..."}
ollama list # at least one modelCloud vs local models. Models tagged
:cloudrun on Ollama's infrastructure and requireollama signin; they are far more capable than what most laptops fit in memory, which makes them the practical choice for delegation. Local models work too and never leave your machine.
No clone or build required — npx fetches it on demand:
claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcpOr install it globally, which also puts the settings CLI on your PATH:
npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcpgit 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"Run the settings CLI as node dist/cli.js …, or npm link to get
ollama-mcp-config on your PATH.
--scope user makes it available in every project; --scope project writes to
.mcp.json in the current repo and shares it with collaborators; --scope local
keeps it to this machine and project.
claude mcp list # ollama: ... - ✔ ConnectedThen restart your Claude Code session — the tool list is read at startup.
Settings resolve from four layers, later winning over earlier:
built-in defaults
user config — ~/.ollama-mcp/config.json (override the path with $OLLAMA_MCP_CONFIG)
project config — ./ollama-mcp.config.json in the server's working directory
environment variables
{
"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
}Setting | Env var | Default | Meaning |
|
|
| How eagerly delegation is used — see below |
|
|
| Models delegation may use |
|
| first allowed cloud model | Model when a call omits one |
|
|
| Permission mode for delegates |
|
|
| Ollama endpoint |
|
|
| Path to the Claude Code CLI |
|
|
| Prompts, transcripts, results |
|
|
| Hard kill for one turn |
|
|
| Output above this is truncated; full text on disk |
Settings are changed from a terminal, never by the model:
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.jsonThen restart your Claude Code session so the server re-reads its config.
There is deliberately no MCP tool for this. See Security model.
allowedModels: [] (the default) permits any model the server offers. With a
non-empty list:
delegate_start rejects a model outside it, naming the allowed set rather than
silently substituting one
ollama_models marks excluded models BLOCKED by allowedModels
the allowed list is embedded in the delegate_start tool description, so the
orchestrator knows the menu without an extra call
the CLI refuses a change that would strand defaultModel outside the new list
This controls how eagerly the orchestrator reaches for delegation, by rewriting the tool descriptions the model actually reads. Changing it requires a session restart, by design.
Mode | Effect |
| The |
| Delegate only when you explicitly ask — "delegate this", "use ollama", "ask qwen". Otherwise the orchestrator does the work itself and does not mention the tools. |
| The orchestrator decides for itself, using criteria baked into the description. |
In auto mode the description tells the orchestrator to delegate work that is
self-contained, cheaply verifiable and context-hungry — bulk file summarisation,
first-pass searches, mechanical refactors, boilerplate and test scaffolding, log
or diff triage — while keeping architecture decisions, security-sensitive
changes, ambiguous requirements and final review for itself. It is also told to
verify delegated claims, for the reason in Operating it.
Tool | Purpose |
| List servable models and report current settings (read-only) |
| Start a task; returns a |
| Send another message to the same session |
| Poll state plus a tail of the delegate's tool calls |
| Collect final output |
| Terminate a running delegate and everything it started |
| List jobs, grouped by conversation |
delegate_startParameter | Type | Notes |
| string | The task. Mutually exclusive with |
| string | Path to a file holding the prompt. Preferred when long. |
| string | Must be in the allowed list. Defaults to |
| string | Working directory for the delegate. Defaults to the server's cwd. |
| enum |
|
| string[] | e.g. |
| string[] | e.g. |
| string | Extra instructions for the delegate |
| number | Cap the delegate's agentic turns |
| string[] | Additional accessible directories |
| number | Block up to N seconds (0–600). Default 0 = return immediately. |
delegate_followup takes job_id or session_id, plus the same
prompt/prompt_file pair and optional permission_mode, max_turns,
wait_seconds.
delegate_start returns a job_id in milliseconds; the delegate keeps running
in the background. This keeps a long task from stalling your session or tripping
an MCP client timeout.
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 textPass wait_seconds on any of those to block instead — useful for short tasks
where a round trip of polling is not worth it.
Every job carries a session_id. Passing its job_id to delegate_followup
resumes the session with full history; the session_id stays stable across turns
while each turn gets a fresh 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)Following up is much cheaper than starting fresh when the delegate already has the relevant context loaded.
Every prompt parameter has a prompt_file counterpart. Internally the prompt is
always written to disk and fed to the CLI over stdin — never as an argv entry
and never through a shell. Backticks, $(...), quotes, newlines and glob
characters pass through verbatim, and there is no argv length limit.
delegate_start({ prompt_file: "/tmp/refactor-brief.md" })Delegates default to defaultPermissionMode (auto). Narrow a specific call:
// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })
// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })Every finished result reports its tool-call count. Weaker models sometimes answer confidently without running anything — during development, one model claimed an environment variable was unset without ever invoking Bash; when pushed, it ran the command and reported the correct value.
A result carrying tool calls: 0 is therefore annotated as unverified:
tool calls: 0 <- answered without using any tools; treat factual claims as unverifieddelegate_status shows the actual trace. A purely conversational follow-up
legitimately has zero — the flag means "nothing backs this", not "something broke".
delegate_cancel({ job_id: "A" })Kills the delegate and everything it started, so a delegate that was midway through a long build does not leave the build running.
Each job writes to ~/.ollama-mcp/jobs/<job_id>/:
File | Contents |
| Exactly what was sent |
| Full |
| Metadata: state, model, tokens, timings, exit code |
| Final output text |
Results longer than maxInlineChars are truncated in the tool response and the
full text read from result.txt. Nothing is pruned automatically — delete the
directory whenever you like.
Cannot reach Ollama at http://127.0.0.1:11434
Ollama is not running. Start ollama serve or open the desktop app. If it listens
elsewhere, set OLLAMA_MCP_BASE_URL.
No models available from Ollama
ollama pull qwen3.5:397b-cloud, and ollama signin for :cloud models.
<model> was retired at … (HTTP 410)
Ollama removed that cloud model. ollama list still shows locally cached
manifests for retired models — check what actually works and update
defaultModel.
Model "x" is not in the allowed list
Working as intended. ollama-mcp-config --allow <models>, then restart.
Tools do not appear in Claude Code
The tool list is read at session start. Restart, or check claude mcp list.
Delegate fails instantly with a launch error
The CLI was not found. Set OLLAMA_MCP_CLAUDE_BIN to the absolute path of
claude.
Everything is slow
Cloud models pay a round trip per turn, and Claude Code sends a large system
prompt (~25k tokens) on every request. Use max_turns to cap agentic loops and
allowed_tools to stop the delegate exploring more than it needs to.
Platform | Status |
macOS | Tested end to end |
Linux | Supported; same POSIX code path as macOS |
Windows | Supported by design, not yet tested on real hardware |
Platform differences are isolated in src/platform.ts:
Binary resolution. On POSIX, spawn searches PATH. On Windows a native
install gives claude.exe while an npm install gives claude.cmd, which
CreateProcess cannot execute directly — so the server walks PATH × PATHEXT
preferring .exe, and falls back to routing a .cmd shim through cmd.exe.
Argument escaping. That fallback applies two layers: MSVCRT argv quoting, then
a caret escape of cmd's own metacharacters (& | < > ^ " ( ) % !). Skipping the
second layer is the classic .cmd command-injection hole. Prompts never touch
this path — they travel over stdin. One limitation: a multi-line
append_system_prompt cannot cross a cmd.exe command line, so the server raises
a clear error pointing at OLLAMA_MCP_CLAUDE_BIN instead of silently mangling it.
Environment allowlist. Windows preserves a much larger set than POSIX.
SystemRoot and windir are not optional — strip them and Winsock fails to
initialise, so the child cannot open a socket even to localhost. Names are matched
case-insensitively but copied with the parent's original spelling.
Cancellation. POSIX children are spawned detached as process-group leaders
and cancelled with process.kill(-pid); Windows uses taskkill /T /F. Either way
the delegate's own subprocesses die with it. The server also kills running
delegates when it shuts down.
Credential isolation is the point. The child environment is constructed from
scratch rather than inherited, and provider variables are stripped before the
Ollama values are applied. This is covered by test/env-unit.mjs, and
test/e2e.mjs poisons the parent with a fake ANTHROPIC_API_KEY and asserts it
never reaches the delegate.
Delegation policy is not model-writable. There is no MCP tool to change
delegationMode or allowedModels. An earlier version had one, which was a
mistake: a model that finds ondemand inconvenient could flip itself to auto
in a single call and then delegate freely. Settings now load once at startup, are
never mutated at runtime, and the tool descriptions state that the policy is not
the model's to change.
This is a guardrail, not a security boundary. An agent with shell access can
still edit the config file. What removing the tool buys you is that such a change
is a visible file edit that only takes effect on the next restart, rather than a
single silent tool call mid-task. To make it airtight, pin the values via --env
on the MCP registration, which overrides the config files:
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.jsDelegates inherit your filesystem. They run as your user in the cwd you
give them, with defaultPermissionMode. Treat a delegated session as you would
any Claude Code session — use disallowed_tools or a read-only permission mode
when handing work to a model you trust less.
npm install # installs and builds
npm run build # tsc
npm run dev # tsc --watchnode 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 runs the three that need no network.
npm login # interactive, once per machine
npm version patch # or minor / major -- tags and bumps
npm publish # prepare script builds first
git push --follow-tagsRun npm publish from a real terminal, not a script or a non-interactive
shell. With WebAuthn/security-key 2FA the CLI completes the challenge by opening
a browser; without a TTY it cannot, and falls back to demanding a TOTP code that
a security key cannot produce (npm error code EOTP). For CI, use a granular
access token with Bypass 2FA instead.
The package is claude-ollama-delegate-mcp and ships only dist/, README.md
and LICENSE. publishConfig.access is public, and prepare runs tsc
before packing, so a stale dist/ can never be published. Preview the tarball
with npm pack --dry-run before shipping.
File | Responsibility |
| MCP server, tool registration and handlers |
| Layered config loading and validation |
| Startup-resolved settings singleton |
| Mode-dependent tool descriptions |
| Child-environment construction and the provider-variable blocklist |
| Windows/POSIX spawn, argument escaping, process-tree kill |
| Job lifecycle, |
| Model discovery and allowlist enforcement |
|
|
MIT — see LICENSE.
Terminate a running delegated Ollama session and everything it started.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job_id to cancel. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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 | |||
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0delegate_canceldelegate_followupdelegate_listdelegate_resultdelegate_startdelegate_statusollama_modelsScored 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Stop copy-pasting between Claude Chat and Claude Code.
One identity across Claude Code, Codex, Cursor, Gemini, Windsurf: shared inbox and handoffs.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
