MCP Server

caliban mcp serve exposes caliban as an MCP server that another agent can drive as a worker or tool. This is the path for a gateway or control plane (e.g. Prospero) to adopt caliban as a backend, and for Codex-style mcp-server parity.

v1 is stdio-only with poll-based unary tools: MCP tool calls are request/response, but the drive core is a stream, so a run is driven by caliban_run → repeated caliban_poll rather than a live push.

caliban mcp serve

The peer connects over stdio and speaks MCP. Because stdio is loopback-inherent, the auth gate admits the peer; CALIBAN_DRIVE_TOKEN only bites on the network-facing HTTP surface.

Tools

Driving a run

1. caliban_run { "prompt": "list the crates", "interactive": false } → note the run_id.
2. Loop caliban_poll { "run_id": …, "cursor": 0 }, advancing cursor to the returned next_cursor each time, appending the events. Each event is a { v, event } envelope (see the event envelope).
3. Stop when status.state is done or failed.

For an interactive run, poll until status.state is awaiting_input, then caliban_send_input { "run_id": …, "text": "…" } to continue, or { "run_id": …, "end": true } to finish.

Answering permission prompts

When a poll returns a permission_request:

{ "tool_use_id": "toolu_01…", "tool_name": "Bash", "input": { "command": "rm -rf build" } }

answer it before the run can proceed:

caliban_permit { "run_id": "…", "tool_use_id": "toolu_01…", "allow": false, "reason": "destructive" }

Registering caliban in an MCP client

Point any MCP client's server config at the stdio command:

{
  "mcpServers": {
    "caliban": {
      "command": "caliban",
      "args": ["mcp", "serve"]
    }
  }
}

The transports and OAuth flow that a remote MCP endpoint layers on top follow ADR 0023; the drive surface itself is defined by ADR 0055.