Optimus MCP + CLI access layer

The engagement surface for Optimus — push your work into the shared brain and query it, from Claude Code (MCP) or the terminal (CLI). Two principal classes:

• Board members — full tool set (pipeline, drafts, campaigns, KB, artifacts, wiki…).
• External customers (OPT-37) — a customer's own agent system (Cursor, bespoke) bound to one org, with access to the org-shared "company brain" surface only (KB ingest/search, artifact registry, enrichment).

The Board API Gateway is the security boundary (JWT auth, route-tier identity gate, per-org visibleClause scoping). The MCP/CLI are thin clients — they hold a token and call HTTP endpoints. Nothing is enforced in the client.

1. Get a token

Board member (you)

node tools/optimus-mcp/issue-token.js <your-github-username>
# writes ~/.nemoclaw-env with OPTIMUS_TOKEN + OPTIMUS_API_URL
echo '[ -f ~/.nemoclaw-env ] && source ~/.nemoclaw-env' >> ~/.zshrc
source ~/.nemoclaw-env

Requires API_SECRET (read from autobot-inbox/.env). The token is a 24h board JWT scoped to your board_members row.

External customer (a board admin mints it for them)

node tools/optimus-mcp/issue-customer-token.js \
  --org umb-advisors \           # tenancy org slug OR uuid
  --label "UMB — Cursor agent" \
  --as <your-github-username>     # you must belong to that org (admins: any org)

This creates a customer_principals row bound to that org and prints the customer's OPTIMUS_TOKEN / OPTIMUS_API_URL. Hand those to the customer. The token:

• is org-scoped — every read fail-closes to that one org (syntheticPrincipal(org_id)), never org-wide;
• can only reach public + org-shared routes — admin / ops-control / viewer-scoped return 403 customer-tier-not-permitted (the customer ceiling, always enforced);
• carries scopes kb:read/write, artifacts:read/write.

Revoke:

# kill ONE token by jti, or the whole principal (all its tokens):
curl -X POST "$OPTIMUS_API_URL/api/auth/customer-token/revoke" \
  -H "Authorization: Bearer $BOARD_API_SECRET" -H "X-Board-User: <username>" \
  -H 'Content-Type: application/json' -d '{"principal_id":"<uuid>"}'

Deactivating the principal (is_active=false) kills every token it holds instantly — the verifier checks is_active on every request.

2. Wire up the MCP server (Claude Code)

Copy the optimus block from mcp.example.json into your .mcp.json. Use the relative path — not a hardcoded /Users/... path:

{
  "mcpServers": {
    "optimus": {
      "command": "node",
      "args": ["tools/optimus-mcp/index.js"],
      "env": { "OPTIMUS_TOKEN": "${OPTIMUS_TOKEN}", "OPTIMUS_API_URL": "${OPTIMUS_API_URL}" }
    }
  }
}

Note: the repo-root .mcp.json historically hardcoded /Users/ericgang/Optimus/.... Replace that args line with the relative form above so the config is portable across machines. (This file is the agent's own runtime config, so it's edited by hand, not by tooling.)

A customer token is auto-detected (JWT iss: optimus-customer): the server registers only the 10 customer-safe tools and disables the board-agent heartbeat. No separate config needed.

Transports

• stdio (default, supported) — each client runs the server locally pointed at the hosted API via OPTIMUS_API_URL.
• HTTP (experimental, OPT-37) — for hosted/on-prem deployments:

  OPTIMUS_MCP_TRANSPORT=http OPTIMUS_MCP_PORT=3399 node tools/optimus-mcp/index.js
  # stateless Streamable-HTTP at http://<host>:3399/mcp

  Validate against your client before relying on it. The Board API JWT is the boundary in both modes.

3. CLI (terminal) — optimus-cli

The non-MCP transport. Same OPTIMUS_TOKEN, same Board API surface, same operations as the MCP server — but a plain CLI you script with and pipe into. This is the "MCP is dead" 80/20 path: tight, predictable control over when the call fires, what args go, and how errors surface. The MCP server, the CLI, and your own fetch are three transports over one thin HTTP layer (client.js); the operation set lives in client.js so they never drift.

export OPTIMUS_TOKEN=...        # board or customer JWT
export OPTIMUS_API_URL=https://preview.staqs.io

node tools/optimus-mcp/cli.js help                 # list commands
node tools/optimus-mcp/cli.js help ingest-doc       # per-command args
node tools/optimus-mcp/cli.js search "voicerail pricing" --limit 3
node tools/optimus-mcp/cli.js ingest-doc --title "VoiceRail PRD" --file ./prd.md
cat notes.md | node tools/optimus-mcp/cli.js push-summary --date 2026-06-08
node tools/optimus-mcp/cli.js ingest-artifact --kind prd --title "VoiceRail PRD" --file ./prd.md
node tools/optimus-mcp/cli.js capture-url https://example.com/spec --kind spec
node tools/optimus-mcp/cli.js list-artifacts --kind prd --json
node tools/optimus-mcp/cli.js get-artifact <uuid>
node tools/optimus-mcp/cli.js enrich-contact <contact-id>

(After npm i -g/npx, the optimus-cli bin replaces node tools/optimus-mcp/cli.js.)

• Commands map 1:1 to the 10 customer-safe MCP tools (optimus-cli help <cmd> prints the MCP-tool equivalent).
• Content (raw/text) comes from --<arg>, --file <path>, or piped stdin — in that order.
• Output is pretty JSON by default; --json prints compact JSON for piping into jq.
• Every command targets an org-shared endpoint, so the CLI is customer-safe as-is — a customer token works unchanged. Ownership (your user + org) is always derived server-side from the token; the CLI never sends an owner/org parameter.

Not to be confused with tools/optimus-cli/ (bin optimus) — that is the narrow Claude Code session-capture hook (optimus capture-session), not the customer operation surface.

4. Direct API (curl / fetch)

No client at all — the customer's agent can call the Board API directly with its OPTIMUS_TOKEN. This is the lowest-overhead transport and the contract the MCP server and CLI both sit on. Auth is a Bearer token; org + ownership are derived server-side; the customer ceiling enforces the org-shared scope.

# Search the company brain
curl -sX POST "$OPTIMUS_API_URL/api/search" \
  -H "Authorization: Bearer $OPTIMUS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"query":"voicerail pricing","limit":3}'

# Ingest a document (KB)
curl -sX POST "$OPTIMUS_API_URL/api/ingest" \
  -H "Authorization: Bearer $OPTIMUS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"source":"mcp-upload","title":"VoiceRail PRD","raw":"# …","format":"markdown"}'

# Route a typed artifact (registry + KB); same title = new version
curl -sX POST "$OPTIMUS_API_URL/api/artifacts" \
  -H "Authorization: Bearer $OPTIMUS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"VoiceRail PRD","kind":"prd","raw":"# …"}'

# Capture a URL as an artifact
curl -sX POST "$OPTIMUS_API_URL/api/artifacts" \
  -H "Authorization: Bearer $OPTIMUS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/spec","kind":"spec"}'

# List / get artifacts (org-scoped)
curl -s "$OPTIMUS_API_URL/api/artifacts?kind=prd&status=active" -H "Authorization: Bearer $OPTIMUS_TOKEN"
curl -s "$OPTIMUS_API_URL/api/artifacts/<uuid>"                   -H "Authorization: Bearer $OPTIMUS_TOKEN"

# Pull everything captured + linked about a contact / project
curl -s "$OPTIMUS_API_URL/api/artifacts/enrich/contact/<id>" -H "Authorization: Bearer $OPTIMUS_TOKEN"
curl -s "$OPTIMUS_API_URL/api/artifacts/enrich/project/<id>" -H "Authorization: Bearer $OPTIMUS_TOKEN"

| Operation | Method + path | Body / query | |-----------|---------------|--------------| | Search KB | POST /api/search | { query, limit? } | | Ingest doc | POST /api/ingest | { source:"mcp-upload", title, raw, format? } | | Ingest transcript | POST /api/ingest | { source:"transcript", title, raw, format? } | | Push summary | POST /api/ingest | { source:"daily-summary", title, raw, format:"markdown" } | | Ingest artifact | POST /api/artifacts | { title, kind, raw } | | Capture URL | POST /api/artifacts | { url, kind? } | | List artifacts | GET /api/artifacts | ?kind=&status= | | Get artifact | GET /api/artifacts/:id | — | | Enrich contact/project | GET /api/artifacts/enrich/{contact,project}/:id | — |

A board-only endpoint (e.g. POST /api/board/build) returns 403 customer-tier-not-permitted for a customer token — the ceiling holds regardless of transport.

5. Scope tiers (what a token can reach)

| Principal | iss | Reaches | Org scope | |-----------|-----|---------|-----------| | Board human | optimus-board | all tiers (admin requires board human) | own ∪ all member orgs | | Internal agent | optimus-agent | authed-any tiers; org-wide (adminBypass) | trusted org-wide | | Customer | optimus-customer | public + org-shared only | its one org (fail-closed) |

See autobot-inbox/src/route-tiers.js (ADR-014) for the full route→tier map and autobot-inbox/docs/internal/opt-37-mcp-tool-tier-audit.md for the per-tool audit.

6. Packaging (npx)

Once published as @staqs/optimus-mcp, clients can skip the repo checkout:

{ "command": "npx", "args": ["-y", "@staqs/optimus-mcp"],
  "env": { "OPTIMUS_TOKEN": "${OPTIMUS_TOKEN}", "OPTIMUS_API_URL": "${OPTIMUS_API_URL}" } }