Skip to main content
Last updated: 2026-09-06
orca mcp has two faces. orca mcp serve turns the CLI into an MCP server 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, which is how agents consume external MCP servers. See MCP integration for the model. Every subcommand accepts the 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; the runtime resolves them and the CLI passes them through verbatim.

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

​
Tools

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

​
Client configuration

Claude Code, against an existing orca install:
Or install the Orca plugin, which registers the same server and adds the use-orca skill:
Any other MCP client that takes a stdio server definition (Cursor, Codex, and others):
For headless environments, log in first with orca login (device flow); see Authentication.

​
orca mcp list

Lists the catalog entries in the current tenant. Header values are never shown in any listing.
Plain (piped) output is one tab-separated row per entry: name, transport, url, description.

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

​
orca mcp add

Registers a new catalog entry. 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.

​
orca mcp set

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

​
orca mcp remove

Deletes a catalog entry. Copies already attached to profiles are unaffected.

​
orca mcp test

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

​
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.
With --json the output is { "agent": <agent>, "server": <spec> }, where server is the copied spec.

​
orca mcp detach

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.
Verified against orca-cli cli-v0.5.0.