Skip to main content
Glama
deenesjakoruzh
hessenpepper

mcp-delegate

by hessenpepper
OverviewSchemaSourceRelated ServersDiscussionsAdmin
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, и это полностью обходит лицензию AGPL/запрет на коммерческое использование agent-loop. См. 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, который берёт base_url/model/api_key из models.json вместо переменных окружения 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 находится в gitignore, как и .env.

Параллельность

Вызовы MCP-инструментов уже выполняются на отдельных рабочих потоках, поэтому параллельные делегирования работают одновременно без дополнительной обвязки. DELEGATE_MAX_CONCURRENCY (по умолчанию 4, см. .env.example) ограничивает, сколько делегирований — через оба инструмента, на любом бэкенде — выполняется одновременно, чтобы большой веерный запуск не перегрузил локальный сервер моделей или не упёрся в лимиты скорости платного API.

Запуск сервера напрямую (в основном полезно, чтобы проверить, что он запускается без ошибок — затем он ждёт на stdio MCP-клиента):

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". Логирование — best-effort: сбой логирования не уронит в остальном успешное делегирование.

Оба инструмента также добавляют в конец собственного возвращаемого значения строку [tokens: N prompt / N completion / N total ($cost)], когда бэкенд сообщает об использовании, чтобы вызывающий агент видел это сразу без отдельного вызова list_recent_delegations.

Отслеживание стоимости

pricing.json сопоставляет строку модели → {input_per_million, output_per_million} ставки в долларах США. Когда у разрешённой модели вызова есть запись, стоимость вычисляется из фактического использования токенов, логируется в delegations.db (колонка cost_usd) и включается в суффикс [tokens: ...]. Модель без записи логирует cost_usd = NULL — неизвестно, а не считается бесплатной, — чтобы отсутствующая запись не могла молча занизить расходы. Локальные модели обычно не имеют записей по этой причине; действительно бесплатные модели (например, модели OpenRouter :free) получают явную запись {"input_per_million": 0, "output_per_million": 0} вместо того, чтобы быть опущенными.

В отличие от .env/models.json, pricing.json не является секретом и не зависит от окружения, поэтому он коммитится напрямую, а не в gitignore. Цены дрейфуют — поставляемый файл был получен из /api/v1/models OpenRouter 2026-08-21 для моделей, названных в сравнительном прогоне моделей, для которого это и было построено; перезапросите и отредактируйте его, чтобы добавить/обновить модели по мере необходимости.

Захват транскрипта (прогоны сравнения моделей / оценки)

Оба инструмента принимают 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) -> 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
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
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

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

Resources

Related MCP Connectors

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.
    6
    MIT

  • deepseek-subagent-mcp

    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.
    6
    MIT

  • pi-delegate-mcp

    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.
    12
    12
    16
    MIT