> ## 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. # orca mcp > Run Orca as an MCP server for coding agents, and manage the tenant's MCP server catalog and the servers attached to agent profiles. > **Last updated: 2026-09-06** `orca mcp` has two faces. `orca mcp serve` turns the CLI into an [MCP server](/agents/mcp) so a coding agent such as Claude Code can drive the Orca control plane through tools. Every other subcommand manages the tenant's MCP server catalog and copies catalog entries onto [agent profiles](/concepts/profiles), which is how agents consume external MCP servers. See [MCP integration](/concepts/mcp-integration) for the model. Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `remove` and `detach` prompt for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2). Catalog names must match `^[A-Za-z0-9_-]+$` (letters, digits, underscore, hyphen) and `runner` is reserved. Names are injected into the codex runtime's TOML config keys, which is why the CLI is stricter than the server. URLs must be absolute `http` or `https`. Header values may be literals, `${VAR}` environment references, or `secret://name` references to [secrets](/concepts/secrets); the runtime resolves them and the CLI passes them through verbatim. ## orca mcp serve ```bash theme={"dark"} orca mcp serve ``` Runs the Orca control-plane MCP server on stdio. From the moment it starts, stdout carries only JSON-RPC; the startup line and every other diagnostic go to stderr. The process stays alive until the client closes stdin (EOF), then exits cleanly. It never mounts the terminal UI, so it is safe to spawn from any MCP client. `--context` and `--api-url` are honored. Credentials are resolved lazily on the first tool call rather than at startup, so you can register the server with a client before you have logged in. The API URL comes from the `--api-url` flag, then `ORCA_API_URL`, then the selected context (`--context` or `ORCA_CONTEXT`, falling back to the current context), then the baked-in production default. The API key comes from `ORCA_API_KEY`, then the selected context's stored key. A missing key surfaces per call as an in-band tool error (`not logged in to Orca`) that names the fix; a rejected key surfaces the same way as `unauthorized`. Every tool failure is returned as an MCP error result (`isError: true`) whose text contains the fix, because agents act on error text. Results are compact JSON capped at 50,000 bytes; truncation is announced inside the payload. `get_run` and `wait_for_run` return at most the 100 most recent events and report `eventsDropped` when older ones were cut. ```bash theme={"dark"} orca mcp serve --context staging ``` ### Tools | Tool | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `whoami` | Identify the authenticated Orca caller: tenant, role, credential kind, key id. Call this first to confirm auth works. | | `get_usage` | Read the account status: credit wallet balance and the monthly spend cap. | | `list_agents` | List the agents (profiles) in this Orca tenant. | | `get_agent` | Fetch one agent profile by name (model, instructions, skills, tools, everything). | | `create_agent` | Create an agent profile. spec is the AgentProfile body (common fields: model, instructions, skills, mcpServers); the full schema is in the `orca://openapi` resource under `#/components/schemas/AgentProfile`. | | `update_agent` | Replace an agent profile (PUT semantics: send the full desired spec, not a patch). | | `run_agent` | Start an agent run with a prompt. Returns `{runId, sessionId}` immediately; call wait\_for\_run to follow it. Pass sessionId to continue an existing conversation. | | `get_run` | Fetch a run: status plus its buffered events (cheap poll; use wait\_for\_run to block until new events or completion). | | `wait_for_run` | Long-poll a run: blocks until it finishes or timeoutSeconds elapses, returning events after afterEvent. Loop with nextAfterEvent until done is true. | | `list_runs` | List recent runs, optionally scoped to one agent or one session. | | `cancel_run` | Cancel a running run. | | `list_skills` | List the skills available in this tenant (attachable to agents). | | `attach_skill` | Attach a skill to an agent profile. | | `detach_skill` | Detach a skill from an agent profile. | | `storage_list` | List objects in the tenant storage (VFS), optionally under a prefix. | | `storage_read` | Read one storage object. Text comes back inline; binary comes back base64. Large objects are truncated at maxBytes. | | `storage_write` | Write (upsert) one storage object. Pass base64: true when content is base64-encoded binary. | | `publish_agent` | Publish an agent as a public chat endpoint. options maps to the publish request body (visibility, authMode, allowedOrigins, ...; schema in `orca://openapi`). | | `api_request` | Escape hatch for any Orca API operation not covered by a dedicated tool: raw authenticated request against `/api/*`. The full OpenAPI spec is in the `orca://openapi` resource (or GET `{apiUrl}/api/openapi.yaml`). | Argument defaults worth knowing: `list_agents` and `list_skills` return 50 rows unless `limit` is set (max 200); `list_runs` returns 20 (max 200); `storage_list` follows the server default of 100 (max 1000); `wait_for_run` waits 60 seconds unless `timeoutSeconds` is set (1 to 240); `storage_read` caps content at 50,000 bytes unless `maxBytes` is set (1 to 50,000; on `cli-v0.5.0` the implicit default was 65,536). `api_request` accepts `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` and rejects any `path` that does not start with `/api/`. `create_agent` and `update_agent` prefix the result with a warning when `spec.runtime` is the deprecated `general`, which the platform imports as `vercel`. ### Resources | Resource | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `orca://openapi` | Orca OpenAPI specification. The full control-plane API schema, for use with the api\_request tool. Served as `application/yaml`, fetched live from `/api/openapi.yaml` on the configured API URL. | ### Client configuration Claude Code, against an existing `orca` install: ```bash theme={"dark"} claude mcp add orca -- orca mcp serve ``` Or install the Orca plugin, which registers the same server and adds the `use-orca` skill: ```bash theme={"dark"} claude plugin marketplace add okikorg/orca-cli claude plugin install orca@orca ``` Any other MCP client that takes a stdio server definition (Cursor, Codex, and others): ```json theme={"dark"} { "command": "orca", "args": ["mcp", "serve"] } ``` For headless environments, log in first with `orca login` (device flow); see [Authentication](/cli/authentication). ## orca mcp list ```bash theme={"dark"} orca mcp list [--limit ] [--offset ] [--all] ``` Lists the catalog entries in the current tenant. Header values are never shown in any listing. | Flag | Type | Default | Description | | -------------- | ------- | ------- | ------------------------------------------------------------------ | | `--limit ` | integer | `10` | Page size | | `--offset ` | integer | `0` | Page offset | | `--all` | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) | ```bash theme={"dark"} orca mcp list --all --json | jq -r '.[].name' ``` Plain (piped) output is one tab-separated row per entry: `name`, `transport`, `url`, `description`. ## orca mcp get ```bash theme={"dark"} orca mcp get ``` Shows one catalog entry. The terminal and plain views print `name`, `transport`, `url`, `headers` (header names only, never values), and `description`. With `--json` the catalog entry is printed as the server returns it. ```bash theme={"dark"} orca mcp get docs --json ``` ## orca mcp add ```bash theme={"dark"} orca mcp add --name --url [--transport ] [--header ]... [--description ] ``` Registers a new catalog entry. | Flag | Type | Default | Description | | ------------------------- | ------ | -------- | ----------------------------------------------------------------- | | `--name ` | string | required | Server name; must match `^[A-Za-z0-9_-]+$` and cannot be `runner` | | `--url ` | string | required | Absolute `http` or `https` MCP endpoint URL | | `--transport ` | string | `http` | One of `http`, `sse` | | `--header ` | string | none | Header as `KEY=VALUE`; repeatable | | `--description ` | string | none | Human-readable description | If the name is already registered the server answers 409 and the CLI exits with code 2, pointing at `orca mcp set`. With `--json` the created entry is printed. ```bash theme={"dark"} orca mcp add --name docs --url https://mcp.example.com/docs \ --header 'Authorization=Bearer secret://docs-token' --description "Product docs" ``` ## orca mcp set ```bash theme={"dark"} orca mcp set [--rename ] [--url ] [--transport ] [--header ]... [--clear-headers] [--description ] ``` Updates or renames a catalog entry. The CLI fetches the current entry, applies the flags, and writes the whole entry back. At least one flag is required (exit code 2 otherwise). | Flag | Type | Default | Description | | ------------------------- | ------- | ------- | ---------------------------------------------------------------- | | `--rename ` | string | none | New name; must match `^[A-Za-z0-9_-]+$` | | `--url ` | string | none | New absolute `http` or `https` URL | | `--transport ` | string | none | One of `http`, `sse` | | `--header ` | string | none | Header as `KEY=VALUE`; repeatable. Replaces all existing headers | | `--clear-headers` | boolean | `false` | Remove all headers (takes precedence over `--header`) | | `--description ` | string | none | New description; an empty string clears it | Headers are replaced as a set, not merged: pass every header you want to keep. A rename onto a name that already exists exits with code 2. Profiles that already carry a copy of this entry are not updated; detach and attach again to pick up the change. ```bash theme={"dark"} orca mcp set docs --header 'Authorization=Bearer secret://docs-token-v2' --description "" orca mcp set docs --rename product-docs ``` ## orca mcp remove ```bash theme={"dark"} orca mcp remove [--yes] ``` Deletes a catalog entry. Copies already attached to profiles are unaffected. | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ```bash theme={"dark"} orca mcp remove docs --yes --json ``` ```json theme={"dark"} { "name": "docs", "deleted": true } ``` ## orca mcp test ```bash theme={"dark"} orca mcp test [name] orca mcp test --url [--transport ] [--header ]... ``` Probes an MCP server through the platform and reports reachability, latency, and the tools it advertises. There are two modes: pass a registered `[name]` to probe a catalog entry with its stored transport and headers, or pass `--url` to probe an endpoint that is not in the catalog. Passing both, or neither, exits with code 2. `--transport` and `--header` only apply in `--url` mode; passing either with a name is a usage error (exit code 2) that points at `orca mcp set` for changing the stored values. On `cli-v0.5.0` they are silently ignored instead. | Flag | Type | Default | Description | | ------------------------- | ------ | ------- | ------------------------------------------------ | | `--url ` | string | none | Probe this endpoint instead of a catalog entry | | `--transport ` | string | `http` | One of `http`, `sse` (with `--url`) | | `--header ` | string | none | Header as `KEY=VALUE`; repeatable (with `--url`) | The plain view prints `ok`, `latencyMs`, `tools`, and `error` when present; `--json` prints the probe result (`ok`, `latencyMs`, `toolCount`, `tools`, `error`). A reachable but broken server comes back with `ok: false`, and the command then exits with code 1, so scripts can gate on connectivity. ```bash theme={"dark"} orca mcp test docs orca mcp test --url https://mcp.example.com/docs --header 'Authorization=Bearer abc' --json ``` ## orca mcp attach ```bash theme={"dark"} orca mcp attach ``` Copies the catalog entry `name` (its name, transport, URL, and headers) onto the agent profile's `mcpServers` and saves the profile. The copy is a snapshot: later changes to the catalog entry do not reach the profile. If the profile already has a server with that name the command exits with code 2 and suggests detaching first. ```bash theme={"dark"} orca mcp attach researcher docs --json ``` With `--json` the output is `{ "agent": , "server": }`, where `server` is the copied spec. ## orca mcp detach ```bash theme={"dark"} orca mcp detach [--yes] ``` Removes the server named `name` from the agent profile's `mcpServers` and saves the profile. The catalog entry is untouched. If the profile has no server by that name the command exits with code 4. | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ```bash theme={"dark"} orca mcp detach researcher docs --yes --json ``` ```json theme={"dark"} { "agent": "researcher", "name": "docs", "detached": true } ``` Verified against orca-cli `cli-v0.5.0`.