de en es ja ko ru zh

mcp-delegate

Name: mcp-delegate
Author: hessenpepper

by hessenpepper

Overview Schema Source Related Servers Discussions Admin

Python

Local

mcp-delegate

一个 MCP 服务器，为 Claude Code（作为编排者）提供一个工具，将任务委托给一个独立的、完整的代理循环，该循环运行在不同的模型上（本地通过 Ollama，或远程通过 OpenRouter），并拥有自己的工具访问权限（文件、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_transcript — 获取一次委托的完整消息/工具调用记录，前提是它以 capture_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 运行，但 shell 命令并未完全沙箱化，可能逃逸（例如 cd ..）。请将其指向一个你愿意让不受监督的模型读取、写入和执行命令的目录。

护栏说明： 原计划的阶段 4 要求确认 agent-loop 自身的护栏（迭代上限、重复检测）是否生效。由于我们不使用 agent-loop，这不直接适用——我们的循环有自己的 max_iterations 和 timeout_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 参数，该参数从 models.json 中查找 base_url/model/api_key，而不是使用默认的 DELEGATE_* 环境变量——例如，一次调用使用 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，首次使用时创建）：工具、后端、模型、任务文本、开始/结束时间、迭代次数、成功/失败、截断的结果/错误预览，以及后端返回的 token 使用情况。可通过 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} 美元费率。当调用的解析模型有条目时，成本根据实际 token 使用量计算，记录到 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 获取，用于此构建所针对的模型比较 bake-off；重新获取并编辑以根据需要添加/更新模型。

记录捕获（模型比较 / 评估运行）

两个工具都接受 capture_transcript: bool = False。设置后，完整的消息交换——每条模型消息、工具调用和工具结果，而不仅仅是最终答案——都会被记录，返回值会附加 [delegation_id: N] 后缀。使用 get_delegation_transcript(delegation_id) 获取。

这用于通过多个不同的模型/后端运行同一任务，并比较不仅最终答案，还有每个模型如何到达那里（工具选择、格式错误的工具调用、重试）——例如，在挑选生产用模型之前，对候选模型进行 bake-off。默认关闭，因为这是常规委托不需要的额外日志开销。

注册到 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) -> str — 多步骤委托，使用 read_file/write_file/run_bash 工具，范围限定在 working_dir 内。仅返回最终答案，不返回完整记录，除非 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

Name	Required	Description	Default
`task`	Yes
`model`	No
`backend`	No
`working_dir`	Yes
`max_iterations`	No
`timeout_seconds`	No
`capture_transcript`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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

Name	Required	Description	Default
`model`	No
`prompt`	Yes
`backend`	No
`system_prompt`	No
`capture_transcript`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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

Name	Required	Description	Default
`delegation_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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

Name	Required	Description	Default
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

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.

4 tool updatesv0.1.0Aug 23, 2026
- First observeddelegate_agentic_task
- First observeddelegate_task
- First observedget_delegation_transcript
- First observedlist_recent_delegations

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0

Scored 2026-08-23 00:30 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

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

AgentdaOAuth
com.myagentda
Agent-native task management: your AI agent is the interface. Delegate to anyone by email.
Project Management Agent Orchestration Communication
2
AgentSite B
io.github.figgy-ops
Task-first cross-agent collaboration for discussions, review, referrals, and reusable knowledge.
Knowledge & Memory Search
101
handoff-mcp-server A
io.github.josephibra
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Agent Orchestration Autonomous Agents
2
AgentMesh A
io.github.lugdwei
MCP delegation fallback for AI agents to discover capabilities, knowledge, tools, and collaborators.
Agent Orchestration Autonomous Agents Communication
51

Related MCP Servers

handoff-mcp
felkru
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.
Updated 2 months ago (2026-07-21 18:35 UTC)
6
MIT
deepseek-subagent-mcp
Coding Agents Agent Orchestration
gaztrabisme
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.
Updated 10 days ago (2026-09-02 12:46 UTC)
6
MIT
DeepSeek Subagent MCP Server
AI & Machine Learning Agent Orchestration
kira4094
A
license
A
quality
B
maintenance
Lets MCP clients like Codex delegate independent sub-tasks to DeepSeek as a sub-agent via a single tool, with optional context, custom system prompts, and configurable model/temperature settings.
Updated 21 days ago (2026-08-23 06:55 UTC)
1
9
MIT
pi-delegate-mcp
Coding Agents Autonomous Agents
howznguyen
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.
Updated 18 days ago (2026-08-25 19:30 UTC)
12
12
16
MIT