MCP Bridge Overview

Opbox exposes its 405-tool surface to external AI agents via the Model Context Protocol (MCP). The same tools that power the in-app AI Assistant are available over plain HTTPS to Claude Code, Claude Desktop, the Claude Agent SDK, or any MCP-compatible harness. One Bearer token, one URL, one shared catalogue.

What MCP Is

MCP is Anthropic's open protocol for exposing tools and resources to AI agents. An MCP server publishes a catalogue of tools with typed input schemas; an MCP client discovers the catalogue and calls tools as native capabilities. There is no SDK lock-in - the wire format is open.

Opbox runs an MCP server at /api/mcp that wraps the platform's internal tool executor. Bearer authentication, autonomy enforcement, and per-key rate limiting layer on top.

How It Fits the Four-Layer Model

From the overall AI overview:

You in Claude Code  ──[MCP key]──>  Opbox MCP server
                                       │
                                       └─ same tool registry as the in-app assistant

MCP is the road in the four-layer model. It carries external clients into the Opbox tool surface. The fuel (BYOK keys), the engine (Agent worker), and the driver's license (agent member) are all separate concerns.

What's Special About Opbox MCP

Feature	Description
Same registry as the in-app assistant	No second-class tool catalogue. Every tool the assistant uses is exposed (subject to autonomy gating).
HTTP transport	Claude Code, Claude Desktop, and any MCP client over HTTP work without a stdio bridge.
Lazy catalogue	`tools/list` returns ~5KB (categories + core tools); `describe_tools` loads schemas on demand.
Cross-workspace operation	Overseer keys can pass `_targetWorkspaceId` to act on subordinate workspaces with the same tool surface.
Workspace-scoped	A key is bound to one workspace. Cross-tenant action requires explicit oversight.
Autonomy-gated	0-3 levels gate the catalogue and re-check on every call.
Audit-logged	Every tool call writes an `AI_INTEGRATION_EXECUTE` entry.
Two auth paths	`cp_live_*` MCP keys (per-workspace, per-autonomy-level, fine-grained) OR the org's OpenClaw bearer (org-scoped, authenticates as the OpenClaw principal at the org's configured inbound autonomy level).

Common Use Cases

Use case	Pattern
Developer productivity	Connect Claude Code on your laptop to your Opbox workspace; ask read-only questions, draft updates.
CSP citadel oversight	One overseer key, `_targetWorkspaceId` swaps across the client base for read-only audits.
Agent Bridge	Spawn Claude Code subprocesses that drain the AgentTask queue. See Agent Bridge.
Doc-gen runtime	Cloud-fired Claude Code Routine claims tasks from the queue and runs the doc-gen loop. See Document Generation.
External automations	A cron job in your infra calls MCP tools to import/export data, generate reports, or kick off workflows.

What MCP Does NOT Do

It is not a separate AI provider. MCP tools don't run an LLM - they expose Opbox's data/actions to whatever LLM the client is running.
It is not a backdoor for billing. Cost ledger writes are tied to the BYOK keys, not the MCP key. The MCP key controls what the agent can do; the BYOK key controls who pays for the LLM call.
It is not how the in-app assistant works. The in-app assistant calls tools in-process via direct JS invocation. MCP is purely external.

Endpoints

Endpoint	Purpose
`GET /api/mcp/health`	Liveness + key summary. Runs full auth, so 401s on bad key, 503s if addon off.
`GET /api/mcp/tools/list`	Catalogue of available tools (filtered by autonomy and scope).
`GET /api/mcp/tools/list?mode=full`	Full payload including all tool schemas inline.
`POST /api/mcp/tools/call`	Execute a tool. JSON body with `name` and `arguments`.
`POST /api/mcp/tools/call` with `describe_tools`	Load full schemas for specific categories on demand.

Lazy Tool Catalogue

tools/list returns ~5KB by default - categories + core tools - rather than the full payload of all 405 schemas. Categories:

core, matters, tables, documents, forms, files, dashboards, workflows, pdf, csp, equity, esop, visa, accounting, themes, system, agent-queue, doc-gen

Usage flow:

Client receives tools/list with categories + core tools.
AI decides which domain is relevant.
AI calls describe_tools({ categories: ["matters", "tables"] }) to load schemas.
AI proceeds with the now-available tools.

Backwards-compat: passing mode=full returns the legacy full payload.

Cross-Workspace via `_targetWorkspaceId`

An overseer key can pass _targetWorkspaceId in any tool's arguments to act on a subordinate workspace:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_matter",
    "arguments": {
      "_targetWorkspaceId": "ckws_subordinate123",
      "title": "SPV formation for Acme"
    }
  }
}

The underscore prefix marks it as executor metadata - tools never see it; the MCP executor strips it before dispatch. The executor:

Resolves the key's home workspace.
Validates oversight: home must hold an ACTIVE OversightRelationship over the target, or the target's org must be managed by the home's super-org.
On pass: swaps ctx.workspaceId to the target, sets ctx.authorityWorkspaceId to the home.
On fail: returns OVERSEER_TARGET_DENIED, no tool runs.

What's preserved across the swap:

ctx.userId stays the overseer's agent user (audit attribution).
ctx.autonomyLevel stays the overseer key's level.
ctx.apiKeyId stays the overseer key (rate-limit budget).

Prompt injection cannot forge _targetWorkspaceId because the key itself anchors the home workspace.

Tool Catalogue Diff

/api/mcp/catalogue/fingerprint returns a stable SHA-256 projection of the live MCP tool catalogue. A boot-time snapshot captures fingerprints; a nightly cron (/api/cron/tool-catalogue-notify) pages workspace OWNERs when a new release changes the shape of the catalogue (new/renamed/removed tools or arg shape changes - cosmetic description-only churn is suppressed).

Surfaced under Settings > AI > Tool Catalogue for OWNERs.