Skip to main content
Glama
deenesjakoruzh
hessenpepper

mcp-delegate

by hessenpepper
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

mcp-delegate

An MCP server that gives Claude Code (as orchestrator) a tool to delegate a task to a separate, full agentic loop running on a different model (local via Ollama, or remote via OpenRouter), with its own tool access (files, bash, etc.), returning only a final result — functionally equivalent to a native subagent, but model-agnostic.

See mcp-subagent-delegation-plan.md for the full build plan, phased as separate commits/checkpoints.

Status

Phase 1, 2, 3, and 4 complete.

  • delegate_task — single-shot chat completion against a configured OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, OpenRouter, ...).

  • delegate_agentic_task — gives the delegated model its own tool-use loop (read_file, write_file, run_bash) scoped to a caller-specified working directory, running until it stops calling tools, hits max_iterations, or exceeds timeout_seconds.

  • list_recent_delegations — inspect what past delegations (either tool) actually did, without digging through logs or re-running anything.

  • get_delegation_transcript — full message/tool-call transcript for one delegation, when it was run with capture_transcript=True (e.g. for model comparison/eval runs).

Deviation from the original plan: Phase 2 called for wrapping agent-loop as a subprocess. agent-loop only supports Linux/macOS/WSL, and this server needs to run natively on Windows, so we built the in-process loop described as Phase 5's alternative instead — same tool interface, no subprocess/ANSI-stripping complexity, and it sidesteps agent-loop's AGPL/no-commercial license entirely. See delegate/agentic.py.

Safety note: working_dir is caller-specified, not a fixed sandbox — the delegated model gets unattended file/bash access to whatever directory it's pointed at. File tools (read_file/write_file) are scoped to stay within working_dir; run_bash runs with that directory as cwd but shell commands are not fully sandboxed and could escape it (e.g. cd ..). Point this at a directory you're comfortable an unattended model can read, write, and execute commands in.

Guardrail note: the original plan's Phase 4 asked to confirm agent-loop's own guardrails (iteration cap, repetition detection) were active. Since we're not using agent-loop, that doesn't apply directly — our loop has its own max_iterations and timeout_seconds caps (verified in testing), but no repetition detection. A model that gets stuck alternating between two tool calls will run until it hits max_iterations rather than being caught early. Worth adding if that turns out to happen in practice.

Related MCP server: handoff-mcp

Setup

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

Multiple backends

Both tools take an optional backend param that looks up base_url/model/api_key from models.json instead of the default DELEGATE_* env vars — e.g. backend="ollama-local" for one call and backend="openrouter-free" for another in the same turn, each running concurrently. model, if also given, overrides just the model string within that backend.

Reference an env var for a key instead of writing it into models.json directly:

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

models.json is gitignored, same as .env.

Concurrency

MCP tool calls already run on separate worker threads, so concurrent delegations run in parallel with no extra plumbing. DELEGATE_MAX_CONCURRENCY (default 4, see .env.example) caps how many delegations — across both tools, any backend — run at once, to avoid a large fan-out overwhelming a local model server or a paid API's rate limits.

Run the server directly (mostly useful to check it starts without error — it then waits on stdio for an MCP client):

uv run server.py

Logging

Every delegate_task/delegate_agentic_task call — success or failure — is logged to a local SQLite file, delegations.db (gitignored, created on first use): tool, backend, model, task text, start/end time, iteration count, success/failure, a truncated result/error preview, and token usage if the backend returned it. Query it via the list_recent_delegations tool, or directly with sqlite3 delegations.db "select * from delegations order by id desc limit 20". Logging is best-effort — a logging failure won't take down an otherwise-successful delegation.

Both tools also append a trailing [tokens: N prompt / N completion / N total ($cost)] line to their own return value when the backend reports usage, so the calling agent sees it immediately without a separate list_recent_delegations call.

Cost tracking

pricing.json maps model string → {input_per_million, output_per_million} USD rates. When a call's resolved model has an entry, cost is computed from actual token usage, logged to delegations.db (cost_usd column), and included in the [tokens: ...] suffix. A model with no entry logs cost_usd = NULL — unknown, not assumed free — so a missing entry can't silently under-report spend. Local models generally won't have entries for that reason; genuinely free models (e.g. OpenRouter :free models) get an explicit {"input_per_million": 0, "output_per_million": 0} entry instead of being omitted.

Unlike .env/models.json, pricing.json isn't a secret or environment-specific, so it's committed directly rather than gitignored. Prices drift — the shipped file was fetched from OpenRouter's /api/v1/models on 2026-08-21 for the models named in a model-comparison bake-off this was built for; re-fetch and edit it to add/update models as needed.

Transcript capture (model comparison / eval runs)

Both tools take capture_transcript: bool = False. When set, the full message exchange — every model message, tool call, and tool result, not just the final answer — is logged, and the return value gets a [delegation_id: N] suffix. Fetch it with get_delegation_transcript(delegation_id).

This exists for running the same task through several different models/backends and comparing not just the final answer but how each one got there (tool selection, malformed tool calls, retries) — e.g. a bake-off across candidate models before picking one for production use. Off by default since it's extra logging overhead you don't want for routine delegation.

Register with Claude Code

A project-scoped .mcp.json is already checked in (uv run server.py). Restart Claude Code in this directory, or run claude mcp list to confirm it picked up the delegate server, then ask it to call delegate_task with a trivial prompt to confirm the round trip.

Tools

  • delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — single-shot chat completion against the configured backend.

  • delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str — multi-step delegation with read_file/write_file/run_bash tools scoped to working_dir. Returns only the final answer, not the full transcript, unless capture_transcript=True.

  • list_recent_delegations(limit=20) -> list[dict] — most recent logged delegations, newest first.

  • get_delegation_transcript(delegation_id) -> list[dict] — full transcript for one delegation logged with capture_transcript=True.

delegate_task/delegate_agentic_task return errors (bad config, unreachable endpoint, timeout, iteration cap) as "Error: ..." strings rather than raising, so a calling agent can see what went wrong.

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. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observeddelegate_agentic_task
    • First observeddelegate_task
    • First observedget_delegation_transcript
    • First observedlist_recent_delegations
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
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

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hessenpepper/mcp-delegate'

If you have feedback or need assistance with the MCP directory API, please join our Discord server