Skip to main content
Glama

mcp-delegate

Claude Code(오케스트레이터)가 별도의 완전한 에이전트 루프(로컬은 Ollama, 원격은 OpenRouter를 통해)에서 실행되는 다른 모델에 작업을 위임할 수 있는 도구를 제공하는 MCP 서버입니다. 이 루프는 자체 도구 접근 권한(파일, bash 등)을 가지며 최종 결과만 반환합니다. 기능적으로는 네이티브 서브에이전트와 동일하지만 모델에 구애받지 않습니다.

전체 빌드 계획은 mcp-subagent-delegation-plan.md를 참조하세요. 각 단계는 별도의 커밋/체크포인트로 구성되어 있습니다.

상태

1, 2, 3, 4단계가 완료되었습니다.

  • delegate_task — 구성된 OpenAI 호환 엔드포인트(Ollama, LM Studio, vLLM, OpenRouter 등)에 대한 단일 호출 채팅 완성.

  • delegate_agentic_task — 위임된 모델에 자체 도구 사용 루프(read_file, write_file, run_bash)를 제공하며, 호출자가 지정한 작업 디렉터리로 범위가 제한됩니다. 모델이 도구 호출을 중단하거나, max_iterations에 도달하거나, timeout_seconds를 초과할 때까지 실행됩니다.

  • list_recent_delegations — 과거 위임(두 도구 모두)이 실제로 무엇을 했는지 로그를 뒤지거나 다시 실행하지 않고 검사합니다.

  • get_delegation_transcriptcapture_transcript=True로 실행된 경우(예: 모델 비교/평가 실행) 단일 위임에 대한 전체 메시지/도구 호출 기록.

원래 계획과의 차이점: 2단계에서는 agent-loop를 하위 프로세스로 래핑하도록 요구했습니다. agent-loop는 Linux/macOS/WSL만 지원하며, 이 서버는 Windows에서 기본적으로 실행되어야 하므로 5단계의 대안으로 설명된 프로세스 내 루프를 구축했습니다. 동일한 도구 인터페이스, 하위 프로세스/ANSI 제거 복잡성 없음, agent-loop의 AGPL/비상업적 라이선스 문제를 완전히 우회합니다. delegate/agentic.py를 참조하세요.

안전 참고 사항: working_dir은 호출자가 지정하며 고정 샌드박스가 아닙니다. 위임된 모델은 지시된 디렉터리에 대해 무인 파일/bash 액세스 권한을 얻습니다. 파일 도구(read_file/write_file)는 working_dir 내에 머물도록 범위가 제한됩니다. run_bash는 해당 디렉터리를 cwd로 실행되지만 셸 명령은 완전히 샌드박스 처리되지 않아 벗어날 수 있습니다(예: cd ..). 무인 모델이 읽고, 쓰고, 명령을 실행해도 괜찮은 디렉터리를 가리키도록 하세요.

가드레일 참고 사항: 원래 계획의 4단계는 agent-loop 자체 가드레일(반복 상한, 반복 감지)이 활성화되어 있는지 확인하도록 요구했습니다. agent-loop를 사용하지 않으므로 직접 적용되지는 않지만, 우리 루프에는 자체 max_iterationstimeout_seconds 상한이 있습니다(테스트에서 확인됨). 그러나 반복 감지는 없습니다. 두 도구 호출 사이에 갇힌 모델은 조기에 감지되지 않고 max_iterations에 도달할 때까지 실행됩니다. 실제로 그런 일이 발생한다면 추가할 가치가 있습니다.

Related MCP server: deepseek-subagent-mcp

설정

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

여러 백엔드

두 도구 모두 선택적 backend 매개변수를 사용하여 기본 DELEGATE_* 환경 변수 대신 models.json에서 base_url/model/api_key를 조회합니다. 예를 들어 한 호출에는 backend="ollama-local"을, 같은 턴의 다른 호출에는 backend="openrouter-free"를 사용하여 각각 동시에 실행할 수 있습니다. model도 함께 제공되면 해당 백엔드 내에서 모델 문자열만 재정의합니다.

키에 대해 models.json에 직접 작성하는 대신 환경 변수를 참조하세요:

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-nano-9b-v2:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json.env와 마찬가지로 gitignore 처리됩니다.

동시성

MCP 도구 호출은 이미 별도의 작업자 스레드에서 실행되므로 추가 배선 없이 동시 위임이 병렬로 실행됩니다. DELEGATE_MAX_CONCURRENCY(기본값 4, .env.example 참조)는 두 도구 모두, 모든 백엔드에서 한 번에 실행되는 위임 수를 제한하여 대규모 팬아웃이 로컬 모델 서버나 유료 API의 속도 제한을 압도하지 않도록 합니다.

서버를 직접 실행합니다(주로 오류 없이 시작되는지 확인하는 데 유용하며, 그 후 MCP 클라이언트를 위해 stdio에서 대기합니다):

uv run server.py

로깅

모든 delegate_task/delegate_agentic_task 호출(성공 또는 실패)은 로컬 SQLite 파일인 delegations.db(gitignore 처리, 첫 사용 시 생성)에 기록됩니다: 도구, 백엔드, 모델, 작업 텍스트, 시작/종료 시간, 반복 횟수, 성공/실패, 잘린 결과/오류 미리보기, 백엔드가 반환한 경우 토큰 사용량. list_recent_delegations 도구를 통해 쿼리하거나 sqlite3 delegations.db "select * from delegations order by id desc limit 20"로 직접 쿼리할 수 있습니다. 로깅은 최선의 노력 방식입니다. 로깅 실패가 성공적인 위임을 중단시키지 않습니다.

두 도구 모두 백엔드가 사용량을 보고할 때 자체 반환 값에 [tokens: N prompt / N completion / N total ($cost)] 줄을 추가하므로 호출 에이전트는 별도의 list_recent_delegations 호출 없이 즉시 확인할 수 있습니다.

비용 추적

pricing.json은 모델 문자열을 {input_per_million, output_per_million} USD 요율로 매핑합니다. 호출의 해석된 모델에 항목이 있으면 실제 토큰 사용량에서 비용이 계산되어 delegations.db(cost_usd 열)에 기록되고 [tokens: ...] 접미사에 포함됩니다. 항목이 없는 모델은 cost_usd = NULL로 기록됩니다. 알 수 없음, 무료로 가정하지 않음 — 누락된 항목이 지출을 조용히 과소 보고할 수 없습니다. 로컬 모델은 일반적으로 이러한 이유로 항목이 없습니다. 진정으로 무료인 모델(예: OpenRouter :free 모델)은 생략하는 대신 명시적 {"input_per_million": 0, "output_per_million": 0} 항목을 얻습니다.

.env/models.json과 달리 pricing.json은 비밀이나 환경별 파일이 아니므로 gitignore 처리하지 않고 직접 커밋합니다. 가격은 변동됩니다. 배포된 파일은 이 서버가 구축된 모델 비교 베이크오프에서 명명된 모델에 대해 2026-08-21에 OpenRouter의 /api/v1/models에서 가져온 것입니다. 필요에 따라 다시 가져와서 모델을 추가/업데이트하세요.

기록 캡처(모델 비교/평가 실행)

두 도구 모두 capture_transcript: bool = False를 사용합니다. 설정하면 최종 답변뿐만 아니라 모든 모델 메시지, 도구 호출, 도구 결과를 포함한 전체 메시지 교환이 기록되고 반환 값에 [delegation_id: N] 접미사가 추가됩니다. get_delegation_transcript(delegation_id)로 가져옵니다.

이 기능은 동일한 작업을 여러 다른 모델/백엔드에서 실행하고 최종 답변뿐만 아니라 각 모델이 그 결과에 도달한 방식(도구 선택, 잘못된 도구 호출, 재시도)을 비교하기 위해 존재합니다. 예를 들어 프로덕션 사용 전에 후보 모델 간 베이크오프를 수행하는 경우입니다. 일상적인 위임에는 원하지 않는 추가 로깅 오버헤드이므로 기본적으로 꺼져 있습니다.

Claude Code에 등록

프로젝트 범위의 .mcp.json이 이미 체크인되어 있습니다(uv run server.py). 이 디렉터리에서 Claude Code를 다시 시작하거나 claude mcp list를 실행하여 delegate 서버를 인식했는지 확인한 다음, 간단한 프롬프트로 delegate_task를 호출하여 왕복을 확인하세요.

도구

  • delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — 구성된 백엔드에 대한 단일 호출 채팅 완성.

  • delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> strworking_dir로 범위가 제한된 read_file/write_file/run_bash 도구를 사용한 다단계 위임. capture_transcript=True가 아닌 한 전체 기록이 아닌 최종 답변만 반환합니다.

  • list_recent_delegations(limit=20) -> list[dict] — 가장 최근에 기록된 위임, 최신순.

  • get_delegation_transcript(delegation_id) -> list[dict]capture_transcript=True로 기록된 단일 위임에 대한 전체 기록.

delegate_task/delegate_agentic_task는 오류(잘못된 구성, 엔드포인트에 연결할 수 없음, 시간 초과, 반복 상한)를 발생시키는 대신 "Error: ..." 문자열로 반환하므로 호출 에이전트가 무엇이 잘못되었는지 확인할 수 있습니다.

Available Tools

4 tools
delegate_agentic_taskA

Delegate a multi-step task to a model with its own tool-use loop (read_file, write_file, run_bash) scoped to working_dir. Runs until the model stops calling tools, hits max_iterations, or exceeds timeout_seconds. Returns only the final answer, not the full transcript.

The delegated model gets unattended file/bash access within working_dir for the duration of the call - point it at a directory you're comfortable it can read, write, and execute commands in.

Args: task: The task instruction to give the delegated model. working_dir: Directory the model's tools are scoped to. model: Override just the model string for this call. max_iterations: Stop after this many tool-call rounds. timeout_seconds: Wall-clock budget for the whole task. backend: Named backend from models.json (base_url/model/api_key) to use instead of the default DELEGATE_* env vars. model, if also given, overrides the model within that backend. capture_transcript: Log every model message and tool call/result for later retrieval via get_delegation_transcript, instead of just the final answer. Off by default; useful when comparing models (e.g. a bake-off) rather than for routine use.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
modelNo
backendNo
working_dirYes
max_iterationsNo
timeout_secondsNo
capture_transcriptNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully carries the behavioral disclosure burden. It clearly states that the delegated model gets unattended read/write/execute access within working_dir, that only the final answer is returned, that there are termination conditions, and that transcript capture is opt-in. This is comprehensive and honest about side effects and limits.

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?

Despite being long, the description is tightly structured: a core behavior paragraph, a safety warning, then a bulleted Args list. Every sentence earns its place, and the most important info (what it does, termination, permissions) is front-loaded. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex delegation tool with 7 parameters, no annotations, and a dangerous access profile, the description covers all critical aspects: scope, termination, access level, return value, optional transcript capture, and backend override. The existence of an output schema is acknowledged but not required to detailed since it says returns only the final answer. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description is the only source of parameter meaning. It explains every parameter in the Args block, including the nuanced interplay between model and backend (backend as a base_url/model/api_key bundle, and that `model` overrides within that backend). This fully compensates for the schema's lack of 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 opens with a precise verb and resource: 'Delegate a multi-step task to a model with its own tool-use loop...'. It clearly states the operation's scope (working_dir) and distinguishes itself from tools like get_delegation_transcript by explaining that it returns only the final answer, not the full transcript. This is a specific, unambiguous definition that lets an agent know exactly what it does.

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 explains the conditions under which the delegated model stops (no more tool calls, max_iterations, timeout_seconds) and warns about unattended file/bash access. It also suggests capture_transcript for comparison scenarios, indirectly routing to get_delegation_transcript. However, it does not explicitly contrast with delegate_task or state when to choose this tool over that sibling, leaving some inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delegate_taskA

Delegate a single-shot task to a configured OpenAI-compatible model (e.g. local Ollama or OpenRouter) and return its text response verbatim.

Args: prompt: The task/question to send to the delegated model. model: Override just the model string for this call. system_prompt: Optional system prompt to steer the delegated model. backend: Named backend from models.json (base_url/model/api_key) to use instead of the default DELEGATE_* env vars. model, if also given, overrides the model within that backend. capture_transcript: Log the full message exchange for later retrieval via get_delegation_transcript. Off by default; useful when comparing models (e.g. a bake-off) rather than for routine use.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
promptYes
backendNo
system_promptNo
capture_transcriptNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the behavioral burden. It discloses the side-effect of transcript capture, the verbatim return behavior, and backend/model override semantics. It does not discuss latency, cost, or authentication, but those are not critical for selecting or invoking this tool correctly.

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 organized with a front-loaded summary followed by a clear Args block. Every parameter is explained in one or two lines, and there is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-shot delegation tool, the description covers purpose, parameter semantics, backend resolution, and the return behavior. With an output schema present and sibling context available, no critical invocation detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description fully documents all five parameters, including the relationship between backend and model, overriding behavior, and the opt-in nature of capture_transcript. This completely compensates for the schema gap.

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 'Delegate a single-shot task to a configured OpenAI-compatible model' and 'return its text response verbatim.' The 'single-shot' qualifier distinguishes it from the sibling delegate_agentic_task, though it does not explicitly name that sibling.

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?

It gives concrete guidance on when to use capture_transcript ('when comparing models, e.g. a bake-off') and when not ('rather than for routine use'), and explains backend selection versus DELEGATE_* env vars. It does not explicitly describe when to choose delegate_task over delegate_agentic_task, but context signals and the 'single-shot' phrasing provide reasonable guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_delegation_transcriptA

Full message transcript (every model message and tool call/result) for one delegation, if it was run with capture_transcript=True. Get the id from list_recent_delegations. Returns an error string if no transcript was captured for that id.

Args: delegation_id: The id field from a list_recent_delegations row.

ParametersJSON Schema
NameRequiredDescriptionDefault
delegation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/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 the burden. It discloses the error condition for missing transcripts, which is the key behavioral nuance. It does not explicitly state read-only semantics, but that is reasonably implied for a retrieval tool.

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, with two clear sentences and a brief args section. No redundant or filler content; it efficiently conveys all necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is an output schema (as indicated in context), the description need not explain return formats. It covers the essential context: the source of the id, the capture condition, and error behavior. This makes it complete for a single-parameter retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter delegation_id is explained beyond the schema: it is the id from a list_recent_delegations row. This provides actionable meaning on how to obtain the correct value, enhancing the bare integer type definition.

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 returns the full transcript for a delegation, using a specific verb ('get') and resource ('transcript'). It is distinct from siblings (list_recent_delegations lists, delegate_task delegates), so no ambiguity.

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 notes the precondition (capture_transcript=True), the error behavior when no transcript exists, and instructs to obtain the delegation_id from list_recent_delegations. This gives clear when-to-use guidance and differentiates it from alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recent_delegationsA

List the most recent delegate_task / delegate_agentic_task calls (backend, model, task, duration, iterations, success, token usage, USD cost if the model has a pricing.json entry, truncated result), most recent first. Answers "what did the delegated model actually do" without re-running anything.

Args: limit: Max number of records to return (default 20).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the read-only nature (without re-running), sorting (most recent first), truncation of results, and conditional cost reporting. It does not mention pagination or error behavior, but for a simple read-only listing tool these are minor omissions; the disclosed traits exceed typical descriptions.

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 moderately concise, listing the returned fields in a parenthetical that is useful but slightly dense. The core purpose is stated upfront, and the parameter doc is separated. It could be tightened by moving the field list to a separate line, but it remains efficient and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one optional parameter, no annotations, and an output schema (not provided). The description covers the return semantics (fields, ordering, truncation, cost condition) and the read-only intent. Given the simplicity, nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the single parameter 'limit'. It does so explicitly: 'Max number of records to return (default 20).' This adds full semantic meaning beyond the bare schema field, making the tool usable without additional inference.

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 lists recent delegate_task / delegate_agentic_task calls, enumerates the returned fields (backend, model, task, duration, iterations, success, token usage, USD cost, truncated result), and specifies ordering (most recent first). It also states the intended purpose—answering what a delegated model actually did—which distinguishes it from sibling tools that create delegations or fetch full transcripts.

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 a clear use case for inspecting prior delegations without re-running them, but it does not explicitly contrast with siblings like get_delegation_transcript or delegate_task. It lacks explicit when-not-to-use guidance, though the mention of 'without re-running anything' strongly suggests a read-only inspection context.

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. 4 tool updatesv0.1.0
    • First observeddelegate_agentic_task
    • First observeddelegate_task
    • First observedget_delegation_transcript
    • First observedlist_recent_delegations

TDQS

A4.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: delegate_task for single-turn, delegate_agentic_task for multi-step with tool use, list_recent_delegations for querying history, and get_delegation_transcript for retrieving full logs. No overlap.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (delegate_task, delegate_agentic_task, list_recent_delegations, get_delegation_transcript), with clear action prefixes.

Tool Count5/5

Four tools precisely cover the core delegation workflow: create a delegation (two variants), list delegations, and inspect a transcript. No unnecessary extras.

Completeness5/5

The tool set covers creating delegations, retrieving summaries, and fetching full transcripts. No update/delete is needed for delegation records, so the surface is complete for its purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Enables Claude to delegate tasks to external coding agents (Codex or Antigravity) for independent reviews, separate quota usage, and async processing.
    6
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Enables AI coding agents like Claude Code or Codex to delegate tasks to a DeepSeek Harness subagent with its own context window, providing tools for task delegation, result waiting, continuation, and supervision with sandboxed execution.
    6
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Enables delegating coding tasks to a pi agent as a steerable background worker, allowing mid-run redirection, follow-ups, and keeping the delegate's context isolated from your main conversation.
    12
    12
    16
    MIT