orca-mcp

External MCP server for Orca — control worktrees, agent sessions, and orchestration from any MCP client (Claude Desktop, Cursor, VS Code, Hyperagent, custom agents, …).

Orca today is driven by its CLI. This project is a small, zero-dependency Node.js bridge that:

1. Speaks MCP over stdio (local desktop hosts) or Streamable HTTP (remote / multi-tenant)

2. Spawns only the orca binary (execFile, no shell)

3. Exposes a supervised dispatch → await → release workflow for multi-agent orchestration

4. Optionally proxies a local Hindsight MCP next to Orca

Community stopgap for stablyai/orca#13079
(“Expose Orca as an MCP server for session and workspace control”).
When Orca ships a first-party orca mcp, this bridge remains useful as a remote / multi-tenant edge with OAuth.

Protocol target: MCP 2025-11-25 (stdio NDJSON + Streamable HTTP).
Roadmap: migrate HTTP mode toward 2026-07-28 stateless HTTP when clients catch up.

Tested on

Security warning

This server is not a sandbox and not a security boundary.

orca-mcp runs with your OS user privileges. An authenticated caller can:

• spawn coding agents and supervised workers on your machine

• drive Orca terminals (including raw terminal send under default config)

• reach the host filesystem and network indirectly through those agents and the Orca CLI

• execute anything the bridge OS user (and your orca / orca-ide binary) can already do

Defaults are permissive on purpose (back-compat for trusted coordinators):

Always-on guardrails are narrow: HTTP binds 127.0.0.1 only, spawn is execFile of the Orca binary only (no shell), unsupervised worktree create --agent --prompt via raw cli is rejected, master-token compare is timing-safe, and the audit log redacts common secrets. That is not equivalent to “safe for untrusted users.”

Shared or untrusted deployments — turn hardening on

# Supervised coordinators only — drop raw admin CLI (terminal send, worktree rm, …):
export ORCA_BRIDGE_TOOLSETS=status,dispatch
export ORCA_BRIDGE_CLI_HARDENING=1

# Read-only observer (health / inventory / check):
node server.mjs --port 8787 --read-only

Also: put a long random ORCA_BRIDGE_TOKEN in a mode-600 env file (never in git); prefer OAuth on HTTP so the master token is not stored in remote MCP client settings; use a separate OAuth client per coordinator; never hand the master path-token URL to someone you would not give a shell.

Do not expose this bridge to callers you do not trust. Full threat model, assets, and non-goals: docs/threat-model.md. Vulnerability reporting: SECURITY.md.

Related MCP server: nexusm-mcp-server

Why this exists

MCP clients cannot natively control Orca. Shelling out to the CLI works only when the agent already has a shell on the Orca host. Remote coordinators (cloud agents, Hyperagent, another laptop) need a network-facing MCP endpoint with auth. Local desktop hosts need a stdio subprocess they can launch themselves.

orca-mcp runs next to Orca on the host:

  Local host (Claude Desktop / Cursor / VS Code)
       │  stdio NDJSON (orca-mcp --stdio)
       ▼
  orca-mcp  ──execFile──►  orca CLI  ──►  Orca runtime

  Remote MCP client  ──HTTPS──►  Funnel / proxy  ──►  127.0.0.1:8787 (HTTP mode)

Features

• Two transports, one tool surface

  • stdio (orca-mcp --stdio) — local hosts; env-based auth; stdout is JSON-RPC only

  • Streamable HTTP (default) — remote coordinators; OAuth + path-token; loopback bind

• Single MCP tool orca with action:

  • health — Orca reachability + bridge version

  • dispatch — create worktree / inject agent + auto worker_done contract

  • await — poll orchestration inbox (empty/timeout = re-call, not failure)

  • release — settle worker (safe against coordinator-sender close)

  • guide — coordinator discipline (also in COORDINATOR.md)

  • check / cli — lower-level inbox + raw CLI (with handoff guards)

• Capability toolsets (status / dispatch / admin) — opt-in restriction via env/flag; default = all enabled

• OAuth 2.0 + PKCE on HTTP (Dynamic Client Registration) so the master token never sits in the MCP client config

• Path-token URLs (/t/<token>/mcp) for curl / sandboxes

• Per-OAuth-client sender isolation — multiple coordinators on one bridge without fencing each other

• Zero npm dependencies — node server.mjs and done

• Mac LaunchAgent + Linux systemd deploy helpers under deploy/

Current bridge version: 0.2.13 (see VERSION in server.mjs).

Quick start

Local install (stdio)

Desktop MCP hosts (Claude Desktop, Cursor, VS Code, Windsurf, Claude Code) launch the bridge as a subprocess and speak newline-delimited JSON-RPC on stdin/stdout. No browser OAuth — secrets come from the environment (MCP guidance for stdio servers).

Published package: orca-mcp@0.2.13 on npm (pin the version; @latest is fine for throwaways only). Prefer the container image for long-lived or privileged hosts.

Standard config

{
  "mcpServers": {
    "orca": {
      "command": "npx",
      "args": ["-y", "orca-mcp@0.2.13", "--stdio"],
      "env": {
        "ORCA_BRIDGE_TOKEN": "<openssl rand -hex 32>",
        "ORCA_CLI_COMMAND": "orca"
      }
    }
  }
}

Local checkout (no registry):

{
  "mcpServers": {
    "orca": {
      "command": "node",
      "args": ["/absolute/path/to/orca-mcp/server.mjs", "--stdio"],
      "env": {
        "ORCA_BRIDGE_TOKEN": "<openssl rand -hex 32>"
      }
    }
  }
}

Host matrix

Edit the desktop config and restart Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the Standard config JSON above (mcpServers.orca).

# Published package (pin the version):
claude mcp add orca --env ORCA_BRIDGE_TOKEN=… -- npx -y orca-mcp@0.2.13 --stdio

# Local checkout:
claude mcp add orca --env ORCA_BRIDGE_TOKEN=… -- node /absolute/path/to/orca-mcp/server.mjs --stdio

Cursor Settings → MCP → Add new MCP Server, command type:

• Command: npx

• Args: -y orca-mcp@0.2.13 --stdio

• Env: ORCA_BRIDGE_TOKEN, optional ORCA_CLI_COMMAND

Or merge the Standard config into Cursor’s MCP JSON.

# Published package (VS Code 1.102+ MCP support):
code --add-mcp '{"name":"orca","command":"npx","args":["-y","orca-mcp@0.2.13","--stdio"],"env":{"ORCA_BRIDGE_TOKEN":"<token>"}}'

Or add the same object under "mcp": { "servers": { … } } in .vscode/mcp.json / user settings.json (see current VS Code MCP docs for the exact key — it has moved between preview builds).

Cascade → MCP servers → add a stdio server with the Standard config fields (command / args / env), or edit the Windsurf MCP config JSON equivalently.

stdio auth (env only)

stdout is protocol-only. All logs go to stderr in --stdio mode. Do not wrap the process with tools that print banners on stdout.

stdio smoke

export ORCA_BRIDGE_TOKEN="$(openssl rand -hex 32)"
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | npx -y orca-mcp@0.2.13 --stdio
# Expect two JSON-RPC response lines on stdout (initialize + tools/list); banners on stderr only.

Container (GHCR)

Docker's guidance for privileged MCP servers is container over bare npx. The published image runs as non-root UID 1001, bakes no secrets, and the same entrypoint supports HTTP and stdio.

# pin by semver
docker pull ghcr.io/buildcontext/orca-mcp:0.2.13

# stdio (local MCP host launches the container)
docker run --rm -i \
  -e ORCA_BRIDGE_TOKEN \
  -e ORCA_CLI_COMMAND=orca \
  ghcr.io/buildcontext/orca-mcp:0.2.13 --stdio

# HTTP on loopback (publish via Funnel / reverse proxy yourself)
docker run --rm \
  -e ORCA_BRIDGE_TOKEN \
  -e ORCA_BRIDGE_PUBLIC_ORIGIN=https://your-host.example.ts.net \
  -p 127.0.0.1:8787:8787 \
  ghcr.io/buildcontext/orca-mcp:0.2.13

After each release the image is also digest-pinned in the GitHub Release notes. Prefer the digest in production:

# example — replace with the digest from the release:
# docker pull ghcr.io/buildcontext/orca-mcp@sha256:<digest>

MCP Registry metadata lives in server.json (io.github.buildcontext/orca-mcp).

Remote install (Streamable HTTP)

Prerequisites

• Node.js ≥ 18 (22 recommended)

• Orca installed and working on the same machine (orca or orca-ide on PATH)

• A secret master token (≥ 16 chars)

# From npm (HTTP mode):
export ORCA_BRIDGE_TOKEN="$(openssl rand -hex 32)"
echo "Save this token: $ORCA_BRIDGE_TOKEN"
export ORCA_BRIDGE_PUBLIC_ORIGIN="https://your-host.example.ts.net"   # optional; needed for OAuth URLs
npx -y orca-mcp@0.2.13 --port 8787

# Or from a git checkout:
git clone https://github.com/BuildContext/orca-mcp.git
cd orca-mcp
node server.mjs --port 8787

The server binds 127.0.0.1 only. Publish it yourself:

# example: Tailscale Funnel
tailscale funnel --bg 8787
tailscale funnel status

Register in an MCP client

OAuth path (recommended) — URL only, no token in settings:

https://your-host.example.ts.net/mcp

The client discovers OAuth metadata, registers (DCR), opens a browser; you enter the master token once. Issued access tokens live in ~/.orca-bridge-tokens.json.

Direct path token (debug / curl):

https://your-host.example.ts.net/t/<ORCA_BRIDGE_TOKEN>/mcp

Hyperagent default redirect prefix is allowlisted (https://hyperagent.com/). For other clients set:

export ORCA_BRIDGE_REDIRECT_ALLOW="https://your-client.example/,https://hyperagent.com/"

Smoke test

curl -sS -X POST "https://your-host.example.ts.net/t/$ORCA_BRIDGE_TOKEN/mcp" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"orca","arguments":{"action":"health"}}}'

Expect statusProbe.ok: true and a bridge.version.

Supervised orchestration (for coordinators)

Generated from lib/coordinator-doctrine.mjs. Edit the doctrine module, then run npm run docs:build.

Raw worktree create --agent --prompt is rejected (forbidden_handoff). Use the action API:

health → dispatch → await(≤45s)×N → worker_done → release(dispatchId, terminalHandle) → read-only

Full discipline: tool description, action=guide, and COORDINATOR.md.

Example wave:

// 1. start work
{ "action": "dispatch", "spec": "…", "repo": "path:/path/to/repo", "agent": "omp" }

// 2. poll until worker_done (repeat)
{ "action": "await", "runId": "<from dispatch>", "waitMs": 45000 }

// 3. cleanup
{ "action": "release", "dispatchId": "<…>", "terminalHandle": "<worker handle from dispatch>" }

Environment

State files (mode 600 where applicable):

• ~/.orca-bridge-tokens.json — issued OAuth access tokens

• ~/.orca-bridge-sender-pins.json — durable per-client sender pins

Capability toolsets

The multiplexed orca tool is still one MCP name (no renames — agents keep working). Operators can restrict which actions an authenticated caller may invoke.

Tiers

Mapping lives in one module: lib/toolsets.mjs (ACTION_TIERS + CLI_PREFIX_TIERS).

Config precedence

1. --read-only (process argv) → { status } only

2. ORCA_BRIDGE_TOOLSETS → exact set (e.g. status,dispatch)

3. Default → { status, dispatch, admin } (identical to the historical all-tiers-on behavior)

Compat: ORCA_BRIDGE_CLI_ADMIN=1 adds admin to the enabled set when the env list omitted it. It does not override --read-only.

ORCA_BRIDGE_CLI_HARDENING remains the allowlist enforcer on action=cli (warn-don’t-block when off). The toolset admin bit is what unlocks admin prefixes under hardening — one admin concept, not two competing switches.

Default is permissive (owner decision)

All tiers are ON unless you restrict them. Existing coordinators need zero config changes. Restriction is an explicit operator choice.

When a tier is disabled, the bridge returns a structured error (not a bare string):

{
  "ok": false,
  "error": "toolset_denied",
  "required_tier": "dispatch",
  "action": "dispatch",
  "enabled_toolsets": ["status"],
  "detail": "… Set ORCA_BRIDGE_TOOLSETS to include \"dispatch\" …",
  "enable_via": { "env": "ORCA_BRIDGE_TOOLSETS", "example": "status,dispatch", "read_only_flag": "--read-only" }
}

action=health always reports the active set under toolsets (when status is enabled — which it is in every supported config).

Recommended hardened deploy (shared / untrusted)

# Supervised coordinators only — no raw admin cli:
export ORCA_BRIDGE_TOOLSETS=status,dispatch
export ORCA_BRIDGE_CLI_HARDENING=1

# Read-only observer (health / inventory / check):
node server.mjs --port 8787 --read-only
# equivalent: ORCA_BRIDGE_TOOLSETS=status

SHOULD set ORCA_BRIDGE_TOOLSETS (and usually ORCA_BRIDGE_CLI_HARDENING=1) on any bridge reachable by more than a trusted coordinator. Safe posture is one env var away — it is intentionally not the default so existing installs keep working.

Both Streamable HTTP and --stdio resolve toolsets the same way: createToolsetGate({ env: process.env, argv: process.argv }) at process start.

Deploy

macOS (GUI Orca)

Helpers under deploy/macos/:

export ORCA_BRIDGE_TOKEN=…          # or --seed-env-from-pid
export ORCA_BRIDGE_PUBLIC_ORIGIN=https://your-host.ts.net
export ORCA_BRIDGE_DURABLE_CHECKOUT="$(pwd)"   # where server.mjs lives
export ORCA_BRIDGE_NODE_BIN="$(command -v node)"

./deploy/macos/install-mac.sh

Installs a user LaunchAgent (com.orca-mcp.bridge), runtime dir ~/.orca-bridge/, secrets in ~/.orca-bridge/env (mode 600). Does not kill a process already holding :8787 — cutover is a separate step.

Linux (CLI-only / headless)

1. Clone this repo to a durable path (not an ephemeral Orca worktree).

2. Copy deploy/linux/orca-bridge.service → /etc/systemd/system/, edit User, WorkingDirectory, EnvironmentFile, and ExecStart paths.

3. Put secrets in the env file (mode 600):

ORCA_BRIDGE_TOKEN=…
ORCA_BRIDGE_PUBLIC_ORIGIN=https://your-host.ts.net
ORCA_CLI_COMMAND=orca-ide   # if that is your binary name
# recommended on shared hosts:
# ORCA_BRIDGE_TOOLSETS=status,dispatch
# ORCA_BRIDGE_CLI_HARDENING=1

4. systemctl enable --now orca-bridge.service

5. Logs: journalctl -u orca-bridge.service -n 50

Scripts run.sh / watchdog.sh / verify-runtime.sh are optional host helpers; set ORCA_BRIDGE_SERVER to your checkout’s server.mjs.

Security model

Read the blunt Security warning first. Operational facts:

• HTTP mode listens on 127.0.0.1 only — never open the port raw to the internet; terminate TLS at Funnel / reverse proxy.

• stdio mode is a local subprocess: auth is ORCA_BRIDGE_TOKEN from the host env / MCP client config (no OAuth browser flow). stdout carries only JSON-RPC; logs go to stderr.

• Auth: constant-time token compare (tokenMatches); OAuth access tokens (HTTP) are revocable (delete ~/.orca-bridge-tokens.json + restart).

• Process spawn is only the Orca binary — no arbitrary shell through the bridge.

• Full CLI surface is powerful (terminal send, etc.). Default toolsets leave it available for back-compat; restrict with ORCA_BRIDGE_TOOLSETS / --read-only and optionally ORCA_BRIDGE_CLI_HARDENING=1 (see Capability toolsets).

• Append-only audit log (redacted NDJSON under ORCA_BRIDGE_AUDIT_DIR or ~/.orca-bridge) records tool calls for forensics — it is not an access-control layer.

• Rotate master token by setting a new ORCA_BRIDGE_TOKEN, restarting, and re-pairing clients.

• Threat model: docs/threat-model.md. Report vulnerabilities privately: SECURITY.md.

Project layout

server.mjs                     # MCP server: shared handlers + HTTP/stdio transports (zero deps)
server.json                    # MCP Registry metadata (io.github.buildcontext/orca-mcp)
Dockerfile / .dockerignore     # non-root image for GHCR (HTTP + --stdio)
lib/coordinator-doctrine.mjs   # canonical coordinator discipline (guide + docs)
lib/toolsets.mjs               # capability tiers + gate
lib/cli-policy.mjs             # action=cli allowlist policy
lib/security-core.mjs          # pure security helpers
lib/audit.mjs                  # annotations + audit resources
lib/orch-isolation.mjs         # multi-coordinator isolation helpers + unit tests
lib/stdio-transport.test.mjs   # stdio + HTTP smoke (node --test)
scripts/docs.mjs               # npm run docs:build / docs:check
docs/design.md                 # why the bridge is shaped this way (sender pin, inject, OAuth)
docs/threat-model.md           # trust boundaries, threats, mitigations
SECURITY.md                    # private vulnerability reporting + scope
CONTRIBUTING.md                # dev setup, checks, doctrine edit rule
COORDINATOR.md                 # generated supervised-flow discipline (action=guide)
deploy/macos/                  # LaunchAgent installer (HTTP mode)
deploy/linux/                  # systemd unit + host scripts (HTTP mode)
.github/workflows/release.yml  # npm --provenance + GHCR on v* tags

Design rationale (sender pinning, inject recovery, envelope quirks, OAuth): docs/design.md. Threat model: docs/threat-model.md. Contributing: CONTRIBUTING.md.

npm test          # node --test lib/**/*.test.mjs
npm run lint      # syntax check all .mjs
npm run docs:check

Relation to upstream Orca

If you maintain Orca: this repo is a working reference for tool shapes, headless sender pinning on CLI-only hosts, and multi-client isolation. Link from #13079 welcome.

License

MIT — see LICENSE.

Orca is a product of Stably; this project is an independent community bridge, not affiliated with or endorsed by Stably.