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

Per call, 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). A missing or rejected credential returns an in-band tool error whose text contains the fix, so agents self-correct.

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 {...}                          -> {runId}
wait_for_run {runId}                     -> {done: false, events: [...], nextAfterEvent: 12}
wait_for_run {runId, afterEvent: 12}     -> {done: true,  events: [...], nextAfterEvent: 20}

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

Coding Agents

Reference

The Orca MCP server

Auth resolution

Tools

Behavior contract

Following runs

​Auth resolution

​Tools

​Behavior contract

​Following runs

Auth resolution

Tools

Behavior contract

Following runs