Skip to main content
Glama

ollama-mcp

Anthropic 기반 Claude Code 세션에서 Ollama 기반 Claude Code 세션으로 작업을 위임하세요 — 두 세션이 환경 변수를 공유하지 않으면서도 가능합니다.

ollama launch claude --model <model>는 ANTHROPIC_* 변수를 쉘에 내보내는 방식으로 작동합니다. 그래서 일반적으로 자체 터미널이 필요합니다: 변수는 프로세스 전체에 적용되므로 하나의 쉘은 "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 값이 적용되기 전에 삭제되므로, 쉘에 남아 있는 ANTHROPIC_API_KEY가 위임된 실행으로 유출되거나 청구될 수 없습니다.

위임자는 --strict-mcp-config와 MCP 설정 없이 시작되므로, 시작 속도가 빠르고 이 서버를 재귀적으로 호출하는 것을 방지합니다.


사전 요구 사항

요구 사항

참고 사항

Node.js 20+

node --version. 24에서 빌드 및 테스트됨.

Ollama

ollama.com/download. 실행 중이어야 함: ollama serve (데스크톱 앱이 자동으로 수행).

Claude Code CLI

claude.com/code. claude --version.

하나 이상의 모델

ollama pull qwen3.5:397b-cloud

Ollama 계정

:cloud 모델에만 필요 — ollama signin. 로컬 모델은 계정이 필요 없음.

설치 전 구성 요소를 확인하세요:

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"

설정 CLI를 node dist/cli.js …로 실행하거나, npm link를 사용하여 ollama-mcp-config를 PATH에 추가합니다.

범위

--scope user는 모든 프로젝트에서 사용 가능하게 합니다. --scope project는 현재 저장소의 .mcp.json에 작성하여 협업자와 공유합니다. --scope local은 이 머신과 프로젝트로 제한합니다.

확인

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

그런 다음 Claude Code 세션을 다시 시작하세요 — 도구 목록은 시작 시 읽힙니다.

설정

설정은 네 계층에서 확인되며, 나중 계층이 이전 계층보다 우선합니다:

  1. 내장 기본값

  2. 사용자 설정 — ~/.ollama-mcp/config.json ($OLLAMA_MCP_CONFIG로 경로 재정의 가능)

  3. 프로젝트 설정 — 서버 작업 디렉토리의 ./ollama-mcp.config.json

  4. 환경 변수

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

설정

환경 변수

기본값

의미

delegationMode

OLLAMA_MCP_DELEGATION_MODE

ondemand

위임 사용 정도 — 아래 참조

allowedModels

OLLAMA_MCP_ALLOWED_MODELS (쉼표로 구분)

[] (모두 허용)

위임이 사용할 수 있는 모델

defaultModel

OLLAMA_MCP_DEFAULT_MODEL

첫 번째 허용된 클라우드 모델

호출에서 모델을 생략할 때 사용되는 모델

defaultPermissionMode

OLLAMA_MCP_PERMISSION_MODE

auto

위임자의 권한 모드

baseUrl

OLLAMA_MCP_BASE_URL 또는 OLLAMA_HOST

http://127.0.0.1:11434

Ollama 엔드포인트

claudeBin

OLLAMA_MCP_CLAUDE_BIN

claude

Claude Code CLI 경로

stateDir

OLLAMA_MCP_STATE_DIR

~/.ollama-mcp/jobs

프롬프트, 대화록, 결과

jobTimeoutMs

OLLAMA_MCP_JOB_TIMEOUT_MS

1800000

한 턴의 강제 종료 시간

maxInlineChars

OLLAMA_MCP_MAX_INLINE_CHARS

60000

이 이상의 출력은 잘림; 전체 텍스트는 디스크에 저장

설정 변경

설정은 모델이 아닌, 터미널에서 변경됩니다:

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을 새 목록 밖으로 이동시키는 변경을 거부합니다.


위임 모드

이는 오케스트레이터가 위임을 얼마나 적극적으로 사용하는지 제어하며, 모델이 실제로 읽는 도구 설명을 다시 작성합니다. 변경하려면 설계상 세션 재시작이 필요합니다.

모드

효과

off

delegate_* 도구가 완전히 숨겨집니다. ollama_models는 모델이 설정을 계속 보고할 수 있도록 남아 있습니다.

ondemand (기본값)

명시적으로 요청할 때만 위임합니다 — "이것을 위임해", "ollama 사용", "qwen에게 물어봐". 그렇지 않으면 오케스트레이터가 직접 작업을 수행하고 도구를 언급하지 않습니다.

auto

오케스트레이터가 스스로 결정하며, 설명에 내장된 기준을 사용합니다.

auto 모드에서 설명은 오케스트레이터에게 독립적이고, 저렴하게 검증 가능하며, 맥락을 많이 필요로 하는 작업(대량 파일 요약, 첫 번째 검색, 기계적 리팩토링, 보일러플레이트 및 테스트 스캐폴딩, 로그 또는 diff 분류)을 위임하도록 지시하면서, 아키텍처 결정, 보안에 민감한 변경, 모호한 요구 사항 및 최종 검토는 스스로 유지하도록 합니다. 또한 위임된 주장을 확인하도록 지시받습니다. 그 이유는 운영에 있습니다.


도구 참조

도구

목적

ollama_models

제공 가능한 모델을 나열하고 현재 설정을 보고합니다 (읽기 전용)

delegate_start

작업을 시작합니다. 즉시 job_id를 반환합니다

delegate_followup

동일한 세션에 다른 메시지를 보냅니다

delegate_status

상태와 위임자의 도구 호출 꼬리를 폴링합니다

delegate_result

최종 출력을 수집합니다

delegate_cancel

실행 중인 위임자와 그 시작된 모든 것을 종료합니다

delegate_list

대화별로 그룹화된 작업을 나열합니다

delegate_start

매개변수

유형

참고 사항

prompt

문자열

작업. prompt_file과 상호 배타적입니다.

prompt_file

문자열

프롬프트가 포함된 파일의 경로. 길이가 길 경우 선호됩니다.

model

문자열

허용 목록에 있어야 합니다. 기본값은 defaultModel입니다.

cwd

문자열

위임자의 작업 디렉토리. 기본값은 서버의 cwd입니다.

permission_mode

열거형

auto, acceptEdits, bypassPermissions, manual, dontAsk, plan

allowed_tools

문자열([]

예: ["Read","Grep","Bash(git *)"]

disallowed_tools

문자열([]

예: ["Write","Edit"]

append_system_prompt

문자열

위임자를 위한 추가 지침

max_turns

숫자

위임자의 에이전트 턴 수 제한

add_dirs

문자열([]

추가 액세스 가능 디렉토리

wait_seconds

숫자

최대 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가 있습니다. delegate_followup에 job_id를 전달하면 전체 기록과 함께 세션이 재개됩니다. 각 턴이 새로운 job_id를 얻는 동안 session_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 항목으로 전달되거나 셸을 통해 전달되지 않습니다. 백틱, $(...), 따옴표, 줄바꿈 및 글로브 문자는 그대로 전달되며, 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 unverified

delegate_status는 실제 추적을 보여줍니다. 순전히 대화형 후속 질문은 합법적으로 0을 가질 수 있습니다. 이 플래그는 "이것을 뒷받침하는 것이 없다"는 의미이지 "무언가 고장났다"는 의미가 아닙니다.

취소

delegate_cancel({ job_id: "A" })

위임자 및 그 위임자가 시작한 모든 것을 종료하므로, 긴 빌드 도중에 있던 위임자가 빌드를 계속 실행하지 않도록 합니다.


작업 아티팩트

각 작업은 ~/.ollama-mcp/jobs/<job_id>/에 기록됩니다:

파일

내용

prompt.txt

정확히 전송된 내용

stream.jsonl

전체 stream-json 기록, 모든 도구 호출 포함

result.json

메타데이터: 상태, 모델, 토큰, 타이밍, 종료 코드

result.txt

최종 출력 텍스트

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 셸을 cmd.exe를 통해 라우팅하는 방식으로 대체합니다.

인수 이스케이프. 이 대체 방법은 두 개의 레이어를 적용합니다: 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를 주입하고 위임자에게 도달하지 않는지 확인합니다.

위임 정책은 모델이 쓸 수 없습니다. delegationMode 또는 allowedModels를 변경하는 MCP 도구는 없습니다. 이전 버전에는 있었지만 실수였습니다: ondemand가 불편한 모델이 한 번의 호출로 auto로 전환한 다음 자유롭게 위임할 수 있었습니다. 설정은 이제 시작 시 한 번 로드되며, 런타임에 절대 변경되지 않으며, 도구 설명에는 정책이 모델이 변경할 수 있는 것이 아님을 명시합니다.

이것은 가드레일이지 보안 경계가 아닙니다. 셸 액세스 권한이 있는 에이전트는 여전히 구성 파일을 편집할 수 있습니다. 도구를 제거함으로써 얻는 이점은 그러한 변경이 작업 중간에 한 번의 조용한 도구 호출이 아니라 다음 재시작 시에만 적용되는 눈에 보이는 파일 편집이 된다는 점입니다. 완전히 차단하려면 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 model

npm 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으로 타르볼을 미리 보십시오.

레이아웃

파일

책임

src/index.ts

MCP 서버, 도구 등록 및 핸들러

src/settings.ts

계층적 구성 로딩 및 검증

src/config.ts

시작 시 해결된 설정 싱글톤

src/descriptions.ts

모드별 도구 설명

src/env.ts

자식 환경 구성 및 공급자 변수 차단 목록

src/platform.ts

Windows/POSIX 생성, 인수 이스케이프, 프로세스 트리 종료

src/jobs.ts

작업 수명 주기, stream-json 파싱, 취소

src/models.ts

모델 검색 및 허용 목록 적용

src/cli.ts

ollama-mcp-config 설정 CLI


라이선스

MIT — LICENSE 참조.

Available Tools

7 tools
delegate_cancelCancel a delegated taskA

Terminate a running delegated Ollama session and everything it started.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe job_id to cancel.

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idNoA job_id from any earlier turn of the conversation.
promptNoThe next message. Use prompt_file for long prompts.
max_turnsNoCap the delegate's agentic turns for this turn.
session_idNoThe Claude Code session id, as an alternative to job_id.
prompt_fileNoPath to a file holding the next message.
wait_secondsNoBlock up to this many seconds before returning.
permission_modeNoOverride the permission mode for this turn.

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum jobs to list. Default 20.
stateNoFilter by state.

TDQS

C2.9/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe job_id to collect.
wait_secondsNoBlock up to this many seconds for the job to finish.

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for the delegated session. Defaults to the server's cwd.
modelNoOllama model id. Must be in the allowed list. Defaults to the configured default.
promptNoThe task for the Ollama-backed session. Use prompt_file for long prompts.
add_dirsNoAdditional directories the delegate may access.
max_turnsNoCap the delegate's agentic turns.
prompt_fileNoPath to a file holding the prompt. Preferred for long or special-character-heavy prompts.
wait_secondsNoBlock up to this many seconds for completion. Default 0.
allowed_toolsNoTool allowlist, e.g. ['Read','Grep','Bash(git *)'].
permission_modeNoPermission mode for the delegate. Defaults to the configured default.
disallowed_toolsNoTool denylist, e.g. ['Write','Edit'].
append_system_promptNoExtra instructions appended to the delegate's system prompt.

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe job_id returned by delegate_start or delegate_followup.
wait_secondsNoBlock up to this many seconds waiting for completion.
progress_limitNoHow many recent activity lines to show. Default 15.

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

  1. 7 tool updatesv1.0.0
    • First observeddelegate_cancel
    • First observeddelegate_followup
    • First observeddelegate_list
    • First observeddelegate_result
    • First observeddelegate_start
    • First observeddelegate_status
    • First observedollama_models

TDQS

A4/5.0

Scored across 7 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers