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.

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.