The Orca MCP server

orca mcp serve runs an MCP server on stdio that exposes Orca’s control plane to any MCP client. It ships inside the orca CLI, so there is nothing extra to install and it reuses the CLI’s stored credentials.

claude mcp add orca -- orca mcp serve

Other clients register {"command": "orca", "args": ["mcp", "serve"]} (JSON) or the TOML equivalent.

Auth resolution

Auth is resolved once, lazily, on the first tool call, checking in order: the CLI’s --context selection, then ORCA_API_KEY and ORCA_API_URL environment variables, then the active context in ~/.config/orca/config.json (written by orca login). The resulting client is cached for the life of the orca mcp serve process. A missing or rejected credential is reported fresh on every call, since nothing was cached, and its in-band tool error states the fix.

Tools

Tool	What it does
`whoami`	Tenant, role, credential kind, key id for the stored credential. Call first.
`get_usage`	Credit wallet balance plus the monthly spend cap.
`list_agents` / `get_agent`	Enumerate or fetch agent profiles.
`create_agent` / `update_agent`	Create or replace a profile; `spec` is the AgentProfile body (schema in `orca://openapi`).
`run_agent`	Start a run: `{agent, prompt, title?, sessionId?}` returns `{runId, sessionId}` immediately.
`get_run`	Status plus buffered events (cheap poll).
`wait_for_run`	Long-poll: blocks until the run finishes or `timeoutSeconds` (max 240) elapses; returns `{status, done, events, nextAfterEvent}`. Loop with `afterEvent: nextAfterEvent` until `done`.
`list_runs`	Recent runs, filterable by agent or session.
`cancel_run`	Cancel a running run.
`list_skills` / `attach_skill` / `detach_skill`	Skill catalog and per-agent wiring.
`storage_list` / `storage_read` / `storage_write`	Tenant object storage; reads are byte-capped, binary rides base64.
`publish_agent`	Expose an agent as a public chat endpoint.
`api_request`	Raw authenticated `{method, path, query?, body?}` against any `/api/*` operation.

One resource: orca://openapi, the live OpenAPI spec (also public at https://api.orcapods.ai/api/openapi.yaml), which documents everything api_request can reach.

Behavior contract

Results are compact JSON, capped near 50KB and 100 events per call, with truncation always announced in the payload. Narrow requests (limit, prefix, maxBytes) to page through the rest.
Failures are in-band MCP error results whose text states the fix (for example Run: orca login (or set ORCA_API_KEY)), never silent.
The server writes nothing to stdout except JSON-RPC; diagnostics go to stderr.

Following runs

MCP tools are request and response, so streaming is modeled as a long-poll loop:

run_agent {...}   returns {runId}
wait_for_run {runId}   returns {done: false, events: [...], nextAfterEvent: 12}
wait_for_run {runId, afterEvent: 12}   returns {done: true, events: [...], nextAfterEvent: 20}

Each call returns as soon as the run finishes, or after timeoutSeconds with whatever arrived; afterEvent deduplicates across calls.

Tool-by-tool reference, including input fields and the orca://openapi resource: orca mcp.

The tools above are the how. Build it with your coding agent is the what: the loop a session runs with them, and the table that says which kind of defect belongs in which file.

Coding Agents

Reference

The Orca MCP server

Auth resolution

Tools

Behavior contract

Following runs

Next

​Auth resolution

​Tools

​Behavior contract

​Following runs

​Next

Auth resolution

Tools

Behavior contract

Following runs

Next