@agent-dispatch/mcp-server

Why this exists

Local AI assistants are effective planners. They hit operational limits when work becomes long-running:

• A deep-research sweep across fifty pages of docs.

• An account-wide audit that has to touch every service.

• A multi-hour job that has no business sitting in your IDE's context window.

Running this inline consumes context, blocks the lead-agent session, and loses continuity when the local process stops.

AgentDispatch is the missing tool. One MCP server gives your assistant a single primitive: spawn a cloud agent with this instruction, come back later for the result. The work runs on managed cloud compute. Status, logs, and the final output flow back through the same MCP channel.

• ☁️ Cloud execution plane. AWS Bedrock AgentCore today; new clouds plug in through one small adapter contract.

• ⏱️ Built for long-running work. Sessions for stateful runs. Runtime mode for provisioned per-task resources. Same MCP contract.

• 🔭 Full visibility. Status, paginated logs, results, cancellation — over MCP, the SDK, or the CLI.

• 🪶 Simple defaults. SQLite state. stdio transport. Zero hidden services. Runs locally, in CI, or on a server.

What it does

A single MCP server exposes ten tools to your assistant:

The model side looks like this:

check_cloud_agent_runtime({ runtime: "research-agent" })
// → { ok: true, checks: [...] }

spawn_cloud_agent({ instruction: "Audit our S3 buckets for public read and report findings." })
// → { taskId: "task_...", status: "queued", cloudAgent: { ... } }

get_task_status({ task_id: "task_..." })
get_task_logs({ task_id: "task_...", cursor: 0, limit: 200 })
get_task_result({ task_id: "task_..." })

All tool inputs are validated with Zod. See src/schemas.ts for the exact shapes.

Agent-facing contract

spawn_cloud_agent is intentionally small. Runtime profiles supply the provider, account, backend, target mode, framework, model, protocol, and default tools.

Tool inputs use MCP-friendly snake_case. Responses return the same camelCase object shape as the AgentDispatch SDK and core runtime.

{
  "runtime": "research-agent",
  "instruction": "Run the background research task and report progress.",
  "protocol": "a2a",
  "context": {
    "repo": "agent-dispatch",
    "priority": "background"
  }
}

Immediate response:

{
  "taskId": "task_...",
  "status": "queued",
  "provider": "aws",
  "accountProfile": "dev-aws",
  "capability": "agent-runtime",
  "backend": "aws-agentcore",
  "poll": {
    "statusTool": "get_task_status",
    "logsTool": "get_task_logs",
    "resultTool": "get_task_result"
  },
  "cloudAgent": {
    "protocol": "a2a",
    "provider": "aws",
    "backend": "aws-agentcore",
    "accountProfile": "dev-aws",
    "sessionId": "ad-f7221e93f25499a0a1fc0160f63c7621",
    "invocation": {
      "type": "aws.agentcore.invoke_agent_runtime",
      "runtimeUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/.../invocations/",
      "sessionHeaderName": "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id",
      "payloadFormat": "a2a.jsonrpc.message-send"
    },
    "a2a": {
      "transport": "json-rpc-2.0-http",
      "messageMethod": "message/send",
      "agentCardPath": "/.well-known/agent-card.json"
    }
  }
}

If the agent does not provide enough information, the server returns a structured clarification instead of failing late:

{
  "status": "needs_clarification",
  "retry_tool": "spawn_cloud_agent",
  "questions": [
    { "id": "instruction", "question": "What task should the cloud subagent run?" },
    { "id": "runtimeArn", "question": "Which AWS AgentCore runtime ARN should this cloud subagent use?" }
  ],
  "available_runtimes": []
}

The agent can answer the clarification directly on the next spawn_cloud_agent call:

{
  "instruction": "Audit our S3 buckets for public read.",
  "runtimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/..."
}

Runtime-mode clarifications work the same way with ecrImageUri, executionRoleArn, and optional environmentVariables.

Supported clients and frameworks

Anything that speaks MCP works. The common clients today:

• Claude Code — add it to ~/.claude/mcp_settings.json or your project's MCP config.

• Codex — add this server as a local MCP server for cloud handoff tasks.

• OpenClaw — call spawn_cloud_agent from inside any task that should leave the local runtime.

• Hermes — move long-running reasoning and tool-rich runs to managed cloud infrastructure.

• Claude Desktop, Cursor, Continue, Goose, Zed — same JSON, different config file.

spawn_cloud_agent and dispatch_task both accept an optional framework string, and runtime profiles carry a default. AgentDispatch does not interpret the value; the worker does. That means OpenClaw-style, Hermes-style, Strands, LangChain, or custom workers can all fit the same MCP contract as soon as your cloud worker knows how to handle the framework.

Quick start

npm install \
  @agent-dispatch/core \
  @agent-dispatch/mcp-server \
  @agent-dispatch/store-sqlite \
  @agent-dispatch/adapter-aws-agentcore

npx agentdispatch-mcp --config agentdispatch.config.json --check

Wire it into your MCP client:

{
  "mcpServers": {
    "agentdispatch": {
      "command": "npx",
      "args": ["agentdispatch-mcp", "--config", "/abs/path/agentdispatch.config.json"]
    }
  }
}

The defaults come from your runtime profile. From the model side, spawn_cloud_agent({ instruction }) is the only call required for the common path.

How it works

   Claude Code · Codex · OpenClaw · Hermes · any MCP client
                          │ stdio
                          ▼
   ┌─────────────────────────────────────────────┐
   │       @agent-dispatch/mcp-server            │   ← this repo
   └─────────────────────┬───────────────────────┘
                         │
                         ▼
   ┌─────────────────────────────────────────────┐
   │           @agent-dispatch/core              │   ← contracts + dispatch
   └──────┬──────────┬───────────────────────────┘
          │          │
          ▼          ▼
   ┌──────────┐  ┌──────────────────────────────────┐
   │  store   │  │  adapter (AWS Bedrock AgentCore) │
   │ (sqlite) │  │      ↓                           │
   └──────────┘  │  cloud worker — runs the task    │
                 └──────────────────────────────────┘

1. Local assistant issues spawn_cloud_agent over MCP.

2. MCP server validates input, hydrates defaults from a runtime profile, calls the core runtime.

3. Core picks the capability and adapter, persists the task, dispatches.

4. Adapter invokes the worker in your cloud.

5. Worker runs an agent framework on managed cloud infrastructure.

6. Status, logs, results, and optional cloudAgent metadata flow back through the same path.

Configuration

Minimal AWS Bedrock AgentCore session-mode config:

{
  "stateDir": ".agentdispatch",
  "accounts": {
    "dev-aws": {
      "provider": "aws",
      "region": "us-west-2",
      "credentialSource": "aws-sdk-default"
    }
  },
  "backends": {
    "agentcore-dev": {
      "adapter": "aws-agentcore",
      "account": "dev-aws",
      "details": {
        "region": "us-west-2",
        "runtimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-runtime",
        "protocol": "a2a"
      }
    }
  },
  "runtimes": {
    "research-agent": {
      "provider": "aws",
      "account": "dev-aws",
      "capability": "agent-runtime",
      "backend": "agentcore-dev",
      "target": { "mode": "session" },
      "protocol": "a2a",
      "framework": "strands",
      "runtimeTools": { "enabled": ["web-search", "code-interpreter"] }
    }
  },
  "defaults": {
    "runtime": "research-agent"
  }
}

Once defaults.runtime is set, spawn_cloud_agent only needs an instruction. The framework, model, runtimeTools, and protocol values are passed through to the worker.

Validate before connecting an MCP client:

npx agentdispatch-mcp --config agentdispatch.config.json --check

Interaction model

spawn_cloud_agent is the control-plane call. After spawn, the lead agent can:

• Poll via get_task_status, get_task_logs, and get_task_result.

• Continue native subagent interaction with returned cloudAgent protocol metadata.

• Use A2A JSON-RPC message/send when the runtime protocol is a2a.

• Cancel through AgentDispatch so provider references remain durable.

Real-world use cases

• Deep research from chat. Codex or Claude Code spawns a cloud agent: "Read the last 90 days of CloudTrail anomalies and propose detection rules."

• Parallel codebase audits. A lead agent fans out a dozen spawn_cloud_agent calls, one per service, then aggregates reports.

• Long-running OpenClaw runs. OpenClaw plans locally, then dispatches multi-hour execution to a managed AgentCore worker.

• Tool-rich Hermes jobs. Hermes uses cloud-side tools that are not available to the local process.

The rest of AgentDispatch

Development

npm install
npm run typecheck
npm test
npm run build

Contributing

PRs, issues, and adapter contributions are welcome. See CONTRIBUTING.md for the local workflow.

If you ship a new framework worker or a new cloud adapter, open a discussion so it can be linked from the org README.

License

Apache-2.0. See LICENSE.