agent-dispatch MCP server
Commit 10 Nov 2026Memungkinkan agent Claude Code untuk mendelegasikan tugas ke agent lain di direktori proyek yang terpisah melalui orkestrasi multi-agent.
Juga dikenal sebagai ginkida/agent-dispatch
- Stars
- 31
- Tools
- 5
- Unduhan, 30 hari
- —
- Versi terbaru
- —
- Commit terakhir
- 10 Nov 2026
- Lisensi
- MIT
Apa itu agent-dispatch MCP?
agent-dispatch adalah MCP server. Memungkinkan agent Claude Code untuk mendelegasikan tugas ke agent lain di direktori proyek yang terpisah melalui orkestrasi multi-agent. Server ini menyediakan 5 tool, seperti name, preview_lines, description.
Ringkasan dibuat dari README proyek
Tentang agent-dispatch MCP server
agent-dispatch memungkinkan pengguna Claude Code untuk mendelegasikan tugas kompleks ke agent spesialis di direktori proyek yang berbeda. Dengan mengorkestrasi beberapa sesi Claude Code, agent utama dapat memberikan perintah kepada agent lain yang memiliki MCP server, file CLAUDE.md, dan toolset unik mereka sendiri. Hal ini memungkinkan workflow terdistribusi di mana satu sesi dapat mengoordinasikan pekerjaan di berbagai lingkungan seperti repositori kode, gateway infrastruktur, atau platform analitik.
Pengguna menyiapkan sistem dengan mendaftarkan direktori proyek lokal sebagai agent melalui command line. Server ini mendukung berbagai metode autentikasi termasuk OAuth, API keys, dan langganan Claude. Untuk mengelola kompleksitas, developer dapat menggabungkan agent yang terkait ke dalam grup yang berbagi konteks dan deskripsi. Sistem ini menyediakan tool seperti list_agents, inspect_agent, dan dispatch untuk mengelola interaksi tersebut. Sistem juga melacak metrik terukur seperti median cost dan durasi untuk membantu Anda merencanakan workflow multi-agent secara efektif.
Apa yang bisa Anda lakukan dengannya
- 1Delegasi tugas lintas proyekSeorang developer dapat menginstruksikan agent utama untuk meminta log container dari agent infrastruktur yang berada di direktori berbeda.
- 2Koordinasi grup multi-agentSesi orkestrasi dapat mengelola sekelompok agent untuk melakukan pekerjaan yang mencakup aspek kode, deployment, hingga verifikasi.
- 3Perencanaan biaya dan performaPengguna dapat mengecek estimasi biaya dan durasi tipikal dari sebuah agent sebelum mengirimkan tugas untuk menghindari pengeluaran yang tidak terduga.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Tool agent-dispatch MCP 5
Terdeteksi dari READMEnamepreview_linesdescriptionshared_contextagent
| name | — | |
| preview_lines | — | |
| description | — | |
| shared_context | — | |
| agent | — |
Pengecekan otomatis
Berjalan 13 Nov 2026Laporan lengkap →Belum diverifikasi. Sebuah server memerlukan skor 80, tidak ada temuan serius, dan data yang cukup untuk kami periksa. Cara kerja checks · Yang perlu diperbaiki untuk menambah poin
- Source repository terhubung dan dapat dijangkauginkida/agent-dispatch is public and reachablegithub.com/ginkida/agent-dispatch ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyaTidak diperiksa
- Provenance build (atestasi Sigstore)Tidak diperiksa
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-11-10github.com/ginkida/agent-dispatch ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerTidak diperiksa
- Tidak ada advisory kritis pada paket atau dependensinyaTidak diperiksa
- Tidak ada instruksi tersembunyi untuk model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelNo tool named like delete, drop or execLolos
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHubagent-dispatch
MCP server that lets Claude Code agents delegate tasks to agents in other project directories.
Each agent runs as a separate claude -p session in its own project directory — inheriting that project's MCP servers, CLAUDE.md, and tools. The calling agent just gets the result back.
Related projects can be bundled into a group — a shared brief plus a member list — so one session can coordinate work across them (e.g. code repos + an infra/Portainer gateway + an analytics gateway).
Works with OAuth, API key, and Claude subscription authentication.
AI agents: this README is the canonical doc for using the tool — setup: Quick Start (every step has a deterministic verify), first call:
dispatch, tool selection: Which Tool to Use, failure handling: Error Recovery. Working on this repo instead? See AGENTS.md.
Quick Start
Prerequisite: the Claude Code CLI must be installed and authenticated. Check first:
claude --version # must print a version — if it fails, install Claude Code before continuing
Then:
pip install agent-dispatch # or: pipx install agent-dispatch
# 1. Create config + register the MCP server with Claude Code (user scope)
agent-dispatch init
# 2. Register project directories as agents — REPLACE the example paths with
# real directories on your machine; they must exist (~ is expanded, relative
# paths are resolved). Descriptions are auto-generated from project files.
# No second project handy? Use the zero-setup block below instead.
agent-dispatch add infra ~/projects/infra
agent-dispatch add backend ~/projects/backend
# 3. Smoke test — dispatches a real task to the agent added in step 2 and prints
# the answer; exit 0 on success. Default task when none given:
# "What project is this? Describe in one sentence."
agent-dispatch test infra
# 4. Verify the whole install — prints "All checks passed." and exits 0 on success
agent-dispatch doctor
Zero-setup alternative for steps 2–3 (no second project needed — registers the current directory):
agent-dispatch add self . && agent-dispatch test self "Say hello"
Every Claude Code session now has the dispatch tools. Independent check: claude mcp list must print a line starting with agent-dispatch:. From inside a Claude Code session, the first MCP calls are list_agents(), then dispatch(...).
If init fails to register the MCP server (prints a warning instead of Registered MCP server), register manually:
claude mcp add-json agent-dispatch "{\"type\":\"stdio\",\"command\":\"$(which agent-dispatch)\",\"args\":[\"serve\"]}" --scope user
If test fails with a permission error (error_type: "permission"), grant tool access and re-test:
agent-dispatch update infra --allowed-tools "Bash,Read,Grep" # least privilege
# or, if the agent needs everything (see SECURITY.md for the trade-off):
agent-dispatch update infra --permission-mode bypassPermissions
When to Dispatch
Do dispatch when a task needs tools, files, or context from another project:
- Check container logs via infra agent's Portainer MCP
- Query a database via db agent's postgres MCP
- Read code or run tests in another repository
Don't dispatch when you can do it yourself — dispatching spawns a full Claude session.
MCP Tools Reference
list_agents
Lists all configured agents. Call this first to see what's available.
// Response (capability + permission fields shown only when populated)
[
{
"name": "infra",
"directory": "/home/user/projects/infra",
"description": "Infrastructure agent. MCP: portainer. Stack: Python, Docker",
"healthy": true,
"has_claude_md": true,
"has_mcp_config": true,
"mcp_servers": ["portainer", "postgres"],
"stacks": ["Python", "Docker"],
"dbs": ["Alembic"],
"capabilities": ["docker_logs", "deploy_debug"],
"risky_capabilities": ["restart_services"],
"permission_mode": "bypassPermissions",
"allowed_tools": ["Bash", "Read", "Grep"],
"typical": {"median_seconds": 143.3, "p90_seconds": 178.3, "median_cost_usd": 0.2666}
}
]
mcp_servers, stacks, and dbs are detected from the agent's project files (.mcp.json, Dockerfile, pyproject.toml, Cargo.toml, prisma/, alembic.ini, etc.) so callers can pick the right agent without dispatching a probe.
typical is measured, not declared: it comes from this agent's own recent dispatches in the usage journal and appears only after a few runs. Use it to size timeout_seconds and to know what a call will cost before you make it. It is absent when the journal is off or the agent has too little history — no data is better than a typical duration derived from two runs.
inspect_agent
Cheap detailed lookup — reads the agent's files without spawning a claude session. Returns the full config (timeout, model, budget, permission mode, allowed/disallowed tools), detected MCP/stacks/DBs, plus short previews of CLAUDE.md and README.md when present.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Agent name from list_agents |
preview_lines |
int | no | Max lines of CLAUDE.md/README.md (default 40, max 200, 0 disables) |
Use this before dispatch_async/dispatch to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
It also carries the agent's instructions (its standing orders) and the full typical block — the trimmed one in list_agents plus dispatches, failed and the outcomes breakdown:
"typical": {
"dispatches": 24, "median_seconds": 143.3, "p90_seconds": 178.3,
"median_cost_usd": 0.2666, "failed": 1, "outcomes": {"done": 21, "partial": 2}
}
Groups
A group bundles related agents into a cross-project working set — typically a few code repos plus capability gateways (an infra agent with a Portainer MCP, an analytics agent with a browser + Yandex Metrica). It lets one orchestrating session coordinate work that spans code, deploy, and verification.
A group is a descriptive layer, not an execution engine — there is no router and no state machine. You pick members by reading their hints and coordinate with the normal dispatch tools. Two text fields target two audiences:
description— orchestrator-facing: how to coordinate the group (the order of steps, who to call for what). Surfaced bylist_groups/inspect_group, never injected into a member's prompt.shared_context— member-facing facts (stack names, counter ids, conventions) that hold regardless of which member reads them. Auto-prepended to a member'scontextwhen you passgroup=.
Members reference agents by name; membership is many-to-many (a shared gateway can belong to several groups). Manage groups with the agent-dispatch group CLI (add/list/inspect/update/remove) or by editing agents.yaml.
list_groups() — cheap, no-subprocess readout of every group: description, member count, and each member's use_for hint + health. A member whose agent was removed is flagged "unknown": true rather than crashing.
inspect_group(name) — one group's full brief: description, the complete shared_context, and the member list. For a deep dive on a specific member, call inspect_agent(member) — inspect_group deliberately stays a cheap membership readout.
Using a group — pass group= to dispatch (or per-item in dispatch_parallel). The agent must be a member; its group's shared_context rides along automatically:
# From the shop-web codebase, hand the deploy to the infra gateway.
# The "shop" group's facts (stack name, counter id) are auto-attached.
dispatch(
agent="infra",
task="Redeploy the shop-web container",
caller="shop-web",
goal="ship the checkout fix",
group="shop",
)
group="" (the default) is byte-for-byte identical to a plain dispatch — the shared facts are folded into the context string, so the result cache disambiguates groups automatically and group-less calls are unaffected.
dispatch
One-shot task delegation. Results are cached — identical requests within TTL return instantly.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent |
string | yes | Agent name from list_agents |
task |
string | yes | What to do — be specific, the agent has no context from your conversation |
context |
string | no | Extra context: error messages, code snippets, stack traces |
caller |
string | no | Your project/role — helps the agent understand who's asking |
goal |
string | no | Broader objective — helps the agent make better trade-offs |
response_format |
string | no | "json" to request a single JSON value; the parsed result lands in parsed_result. Empty = free-form text. |
return_ref |
bool | no | When true, returns just a ref + summary preview instead of the full result text. Use fetch_result(ref) to load the full text on demand. |
summary_chars |
int | no | Max chars of result text to include in the ref response (default 500). |
timeout_seconds |
int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
group |
string | no | Group name (from list_groups). The agent must be a member; the group's shared_context (member-facing facts) is auto-prepended to context. Empty = plain dispatch. See Groups. |
# Call — recommended form (always include caller and goal)
dispatch(
agent="infra", # must exist in list_agents()
task="Check container logs for errors related to the scheduler service",
context="Error: TypeError at scheduler.py:42",
caller="backend", # your project/role
goal="debug production crash" # the broader objective
)
// Response (success)
{
"agent": "infra",
"success": true,
"result": "Found 3 errors in container logs: TypeError in scheduler.py:42...",
"session_id": "sess-abc-123",
"cost_usd": 0.02,
"duration_ms": 5000,
"num_turns": 2,
"outcome": "done"
}
// Response (failure — error_type helps you handle programmatically)
{
"agent": "infra",
"success": false,
"result": "",
"error": "Tool_use is not allowed in this permission mode\n\nHint: ...",
"error_type": "permission"
}
error_type values: permission (tool/action denied), timeout, recursion (dispatch depth exceeded), not_found (missing directory or CLI), budget (the claude CLI stopped the session at max_budget_usd), usage_limit (the Claude account hit its rate/session limit), cli_error (other failures). Permission, budget, usage-limit and timeout errors include an actionable hint.
Resumable timeouts: every fresh dispatch pre-assigns a session UUID (--session-id), so a timed-out dispatch still returns a session_id — the partial transcript survives the kill. The timeout error spells out the recovery: resume with dispatch_session(agent, "Continue where you left off", session_id=...), retry with a bigger timeout_seconds, or use dispatch_async.
Denied-tools visibility: in non-interactive mode the claude CLI auto-denies tools the agent isn't allowed to use — the agent then often "succeeds" with an answer like "I need your permission for one read-only query". When that happens the response carries the deterministic signal: denied_tools (parsed from the CLI's permission_denials) plus a hint explaining the result may be incomplete and how to grant access. success stays true — it's a soft signal, not a failure.
// Response (success, but a tool was blocked)
{
"agent": "analysis",
"success": true,
"result": "Here is the offline mapping. To finish I'd need to run one read-only query...",
"denied_tools": ["Bash"],
"hint": "1 tool call(s) were denied by permissions: Bash. The result may be incomplete..."
}
Structured JSON output: pass response_format="json" to ask the agent for a single JSON value. The runner appends an instruction footer ("respond with a single valid JSON value, no fences, no prose") and on success parses the response — the parsed value lands in parsed_result. The raw text is always in result. Parse failures leave parsed_result=None but don't fail the dispatch (soft mode).
// Response with response_format="json"
{
"agent": "infra",
"success": true,
"result": "{\"errors\": 3, \"first_at\": \"14:02\"}",
"parsed_result": {"errors": 3, "first_at": "14:02"}
}
Always pass caller and goal — the dispatched agent sees a structured prompt:
## Goal
debug production crash
## Dispatched by
backend
## Context
Error: TypeError at scheduler.py:42
## Task
Check container logs for recent errors related to the scheduler service
The dispatch protocol and outcome. claude -p on its own does not know it is being driven by another agent: given an ambiguous task it will happily end with "Could you clarify which service you mean?" — a billed run that answered nothing, and one that a plain cache would then serve again for the whole TTL. So every dispatch also appends a short dispatch protocol to the agent's system prompt (--append-system-prompt, never mixed into your task text):
- it is running non-interactively, dispatched by
caller, and nobody will answer a question or approve an action — state the assumption and proceed, take the safer reading when two differ; - a denied tool or a missing thing is something to report, not something to stop on — finish everything else that is possible;
- its time budget is about the agent's timeout (and its spend cap, if one is set) — scope the work to fit; a complete partial answer beats an unfinished perfect one;
- lead with the outcome, then the evidence; list what could not be done and why (this is what makes a
return_refsummary — the head of the text — worth reading); - end with one line,
STATUS: done,STATUS: partialorSTATUS: blocked.
That last line is lifted out of result into outcome — the agent's own verdict, deterministic to check: "done" means complete; "partial" / "blocked" mean the agent says the work is unfinished, the result names what is missing, and a hint spells out the continuation (usually dispatch_session(..., session_id=...)). Read outcome before reading the text. It never flips success, partial / blocked results are not cached, and a dispatch_parallel(..., aggregate=...) labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (settings.dispatch_protocol: false), response_format="json" was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
Startup cost. Each dispatch is a fresh claude session, and a session's preamble — the project's CLAUDE.md, the skill listing, MCP server instructions and tool names — is written to the prompt cache again for every new task text (the task sits in front of it, so two different tasks share none of it). Measured on claude 2.1.322 in a gateway directory: ~32k tokens per dispatch before the agent does anything, which is most of what a short run costs. Two opt-in per-agent switches trim it — agent-dispatch update <name> --no-skills (no skill/command listing, user-level skills included: −27% in that measurement) and --strict-mcp (only the directory's own .mcp.json, no user-scope servers or connectors: −11%; the agent then cannot dispatch others, and loses any tool it got from a user-scope server). Check what an agent actually uses before turning either on; --skills / --no-strict-mcp undo them. A follow-up to the same agent is the opposite case: dispatch_session with the session_id from the previous result re-reads that preamble from cache (measured: $0.005–0.017 per follow-up against $0.089 for a fresh dispatch), so continue a session rather than re-dispatching when the question builds on the last answer. The larger levers stay outside this tool: a cheaper model for gateway agents and a shorter agent CLAUDE.md.
Standing orders. Per-agent instructions (set via add_agent / update_agent or agent-dispatch update <name> --instructions "...") follow the protocol in the same system prompt on every dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike context, which is per call, and unlike the project's own CLAUDE.md, which is written for an interactive session, these are the rules for being dispatched.
// Response (success, but the agent says it did not finish)
{
"agent": "infra",
"success": true,
"result": "Restarted horizon. Could not verify the queue drained: the redis container is not reachable from here.",
"session_id": "sess-abc-123",
"outcome": "partial",
"hint": "The agent reports its work is PARTIAL — read the result for what is missing, then continue in the same session via dispatch_session(agent='infra', task='Continue where you left off', session_id='sess-abc-123') or re-dispatch with what it needed."
}
dispatch_session
Multi-turn: continue a conversation with an agent. First call starts a session, pass session_id back to continue. Never cached.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent |
string | yes | Agent name |
task |
string | yes | Task or follow-up message |
session_id |
string | no | From previous response — empty for new session |
context |
string | no | Extra context |
caller |
string | no | Who is dispatching |
goal |
string | no | Broader objective |
timeout_seconds |
int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
dispatch_session is also the timeout recovery path: a timed-out dispatch returns a session_id — pass it here with task="Continue where you left off" to salvage the partial work instead of restarting.
Turn 1: dispatch_session("infra", "List running containers")
→ session_id: "sess-abc"
Turn 2: dispatch_session("infra", "Restart the nginx one", session_id="sess-abc")
→ agent remembers previous context
dispatch_parallel
Run multiple tasks concurrently. Much faster than sequential dispatch calls.
| Parameter | Type | Required | Description |
|---|---|---|---|
dispatches |
string (JSON) | yes | JSON array of {"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?", "group?"} (a per-item group validates membership up front and auto-injects its shared_context) |
aggregate |
string | no | Agent name to synthesize all results into one answer |
Important: dispatches is a JSON string, not a list.
// Input
[
{"agent": "infra", "task": "check pod logs for errors", "caller": "backend", "goal": "debug crash"},
{"agent": "db", "task": "are all migrations applied?", "caller": "backend", "goal": "debug crash"}
]
// Response (without aggregate)
[
{"agent": "infra", "success": true, "result": "No errors in pod logs", ...},
{"agent": "db", "success": true, "result": "All migrations applied", ...}
]
// Response (with aggregate="backend")
{
"individual_results": [
{"agent": "infra", "success": true, "result": "No errors in pod logs", ...},
{"agent": "db", "success": true, "result": "All migrations applied", ...}
],
"aggregated": {
"agent": "backend",
"success": true,
"result": "Summary: all systems nominal. No pod errors, all migrations applied."
}
}
dispatch_stream
Same as dispatch but shows live progress while the agent works. Use for long-running tasks. Not cached.
Progress notifications keep the latest 100 pending messages, capped at 300 characters each. If output arrives faster than the client can receive it, older notifications are omitted with a count; the final result is unaffected. Disconnecting or cancelling the tool call discards pending notifications and stops buffering new ones. The worker still holds its concurrency slot until it finishes.
Parameters are the same as dispatch except return_ref/summary_chars (streaming is incompatible with ref-mode) and group (group context injection is supported only on dispatch and per-item in dispatch_parallel).
dispatch_dialogue
Two agents collaborate through multi-turn conversation. Never cached.
| Parameter | Type | Required | Description |
|---|---|---|---|
requester |
string | yes | Agent with the problem/context |
responder |
string | yes | Agent with the expertise/tools |
topic |
string | yes | Problem or question to discuss |
max_rounds |
int | no | Max back-and-forth rounds (default: 3, max: 10) |
Each round costs up to 2 dispatches. Agents signal completion with [RESOLVED].
// Response
{
"resolved": true,
"rounds": 2,
"total_cost_usd": 0.04,
"total_duration_ms": 12000,
"final_answer": "Staging had 1 pending migration. Applied successfully.",
"conversation": [
{"agent": "db", "role": "responder", "round": 1, "message": "Which environment?", "cost_usd": 0.01},
{"agent": "backend", "role": "requester", "round": 1, "message": "Staging", "cost_usd": 0.01},
{"agent": "db", "role": "responder", "round": 2, "message": "Applied. [RESOLVED]", "cost_usd": 0.01}
]
}
add_agent
Register a new project directory as an agent. Description is auto-generated from project files if omitted.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Agent name (letters, digits, hyphens, underscores) |
directory |
string | yes | Path to an existing project directory (~ is expanded, relative paths resolved) |
description |
string | no | What this agent can do — auto-generated if empty |
timeout |
int | no | Timeout in seconds (0 = 300; this is a literal default, not settings.default_timeout) |
max_budget_usd |
float | no | Finite max cost in USD per dispatch (0 = inherit settings.default_max_budget_usd; no cap only when that is unset too) |
permission_mode |
string | no | Permission mode (e.g. default, plan, bypassPermissions) |
allowed_tools |
string | no | Comma-separated allowed tools (e.g. "Bash,Read,Edit") |
disallowed_tools |
string | no | Comma-separated disallowed tools |
capabilities |
string | no | Comma-separated capability labels (e.g. "docker_logs,deploy_debug") |
risky_capabilities |
string | no | Comma-separated high-risk labels (e.g. "restart_services") |
instructions |
string | no | Standing orders appended to the agent's system prompt on every dispatch (see the dispatch protocol) |
Pertanyaan tentang agent-dispatch MCP
Tool apa yang disediakan agent-dispatch MCP?
Server ini menyediakan 5 tool, termasuk name, preview_lines, description, shared_context, agent.
Bagaimana cara mendaftarkan agent baru?
Anda dapat mendaftarkan direktori proyek sebagai agent menggunakan command agent-dispatch add <name> <path>.
Apa yang harus saya lakukan jika mendapatkan error permission saat melakukan test?
Anda dapat memberikan akses tool tertentu menggunakan command update, seperti agent-dispatch update <name> --allowed-tools "Bash,Read,Grep", atau gunakan bypass mode untuk mendapatkan full permissions.