> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The Orca MCP server

> orca mcp serve exposes the whole control plane as MCP tools: reference for every tool, auth resolution, and the api_request escape hatch.

`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.

```bash theme={null}
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:

```text theme={null}
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.