MCP Setup

Opbox exposes its platform as an MCP (Model Context Protocol) server, so any MCP-compatible client - Claude Code, Claude Desktop, the Claude Agent SDK, or a custom harness - can drive the same 200+ tool surface that powers the built-in AI assistant. Once a workspace has the AI Agent addon active and an API key issued, an external agent can create matters, update table rows, complete steps, query the knowledge base, run saved SQL, manage cap tables, and more - all over plain HTTPS with a Bearer token.

This guide walks you through creating a key, wiring a client, and verifying the connection.

What is MCP?

MCP is Anthropic's open protocol for exposing tools and resources to AI agents. An MCP server publishes a catalog of tools with typed input schemas; an MCP client discovers that catalog and calls the tools as native capabilities. Opbox runs an MCP server at /api/mcp that wraps the platform's internal tool executor - the same handlers the in-app assistant uses, with Bearer authentication, autonomy enforcement, and per-key rate limiting layered on top.

Before you begin

You need:

• An Opbox workspace with the AI Agent addon installed and active. Install it from Settings -> Addons. Without the addon, every MCP request returns 503 AI Agent addon is not active for this workspace.
• An ADMIN or OWNER role on the workspace. MEMBERs cannot create keys - this prevents self-escalation via the autonomy level.
• An MCP-capable client. Primary target is the Claude Code CLI. Claude Desktop, the Claude Agent SDK, and any other MCP-compatible harness also work - the wire format is identical.

Step 1: Create an MCP key

Each MCP key is bound to an agent user - a pseudo-account scoped to the workspace. Opbox creates the agent automatically when you create the key.

1. Go to Settings -> MCP.
2. Click New MCP Key.
3. In the scope picker, give the agent a name and choose an autonomy level (see Autonomy levels below). Level 0 (read-only) is the default and the safest starting point.
4. Optionally set an expiry (1-365 days). Keys without an expiry run forever until revoked.
5. Pick the tool scopes the agent should see. Scopes narrow the catalog further - a level-2 key with only matters.read scopes will not see table write tools even though the level allows it.
6. Click Create. Opbox returns the raw key once. Copy it immediately and store it in a secrets manager - it cannot be retrieved later. You can see a prefix (cp_live_...) in the settings list after, but never the full key.

The response also contains an mcpConfig JSON snippet pre-filled with the key, URL, and headers - you can paste it straight into a client config. See Step 2.

Keys look like cp_live_ followed by 32 bytes of random data in URL-safe base64.

Step 2: Configure your MCP client

Opbox exposes MCP over HTTP, not stdio. There is no local subprocess - the client makes Bearer-authenticated HTTPS calls straight to https://opbox.app/api/mcp.

Every request must carry two headers:

The X-MCP-Client header is mandatory and cannot be set by browsers in cross-origin requests, which blocks a compromised browser session from calling MCP endpoints even if it had a stolen key.

Claude Code CLI

Claude Code reads MCP server config from ~/.claude.json (user-level) or a per-project .mcp.json. Paste this under mcpServers:

{
  "mcpServers": {
    "opbox": {
      "type": "http",
      "url": "https://opbox.app/api/mcp",
      "headers": {
        "Authorization": "Bearer cp_live_your_key_here",
        "X-MCP-Client": "claude-code"
      }
    }
  }
}

Restart Claude Code and the new server will be picked up on next launch.

If you created the key from Settings -> MCP, the mcpConfig block in the creation response is already in exactly this shape. Copy the mcpServers object verbatim.

Claude Desktop

Claude Desktop uses the same JSON schema. Add the same opbox block to Claude Desktop's MCP config file and restart the app.

Claude Agent SDK and custom clients

Any MCP client that supports HTTP transport works - point it at https://opbox.app/api/mcp, send the two headers above, and you can issue tools/list and tools/call requests straight away. The response envelopes follow the standard MCP { content: [{ type: 'text', text: '...' }], isError?: boolean } shape.

Step 3: Verify the connection

In Claude Code

Run /mcp inside a Claude Code session. You should see your opbox server listed with a connected status and a tool count. If the tool count looks small, your autonomy level is probably capping the catalog - see Autonomy levels.

Try asking Claude something read-only, for example:

List the five most recently updated matters in Opbox.

Claude will pick a tool like list_matters, call it through MCP, and stream back the result.

With curl

You can also hit the MCP endpoints directly:

# Liveness + key summary
curl -H "Authorization: Bearer cp_live_..." \
     -H "X-MCP-Client: curl" \
     https://opbox.app/api/mcp/health

# List the tools this key can call
curl -H "Authorization: Bearer cp_live_..." \
     -H "X-MCP-Client: curl" \
     https://opbox.app/api/mcp/tools/list

# Call a tool
curl -X POST https://opbox.app/api/mcp/tools/call \
  -H "Authorization: Bearer cp_live_..." \
  -H "X-MCP-Client: curl" \
  -H "Content-Type: application/json" \
  -d '{"name":"list_matters","arguments":{"limit":5}}'

/api/mcp/health runs the full auth pipeline, so it 401s on a bad key and 503s if the addon is off. It's a good end-to-end check, not just a liveness ping.

A successful health response:

{
  "status": "connected",
  "workspaceId": "ws_...",
  "toolCount": 47,
  "autonomyLevel": 0,
  "isAgent": false,
  "isOverseer": false
}

Autonomy levels

Every key has an autonomy level from 0 to 3. The catalog returned by tools/list is filtered to tools at or below that level, and tools/call re-checks on execution - so a level-0 key cannot invoke a level-2 tool even if it knows the name.

Start at level 0. Raise it only if the agent demonstrably needs write access, and use short-lived keys (7-30 day expiry) for anything above level 0.

Levels are also a containment mechanism: if a key leaks, the blast radius is bounded by its autonomy. Keys cannot self-elevate.

Tool catalog

The full catalog of MCP tools, their autonomy levels, and input schemas lives at AI Tools Reference. Every tool the in-app assistant can call is also exposed over MCP - there is no separate registry.

Rate limits

Three independent limits apply to every MCP call:

1. Per autonomy tier. A per-key bucket sized by the level's rate limit (300/60/30/10 per minute for levels 0-3). Reads and writes count separately, so a level-2 key can burst 300 reads/min without consuming its 30 writes/min.
2. Per-key global ceiling. Configurable on the key (default 120 req/min, max 1000). Applied on top of the tier limit - a level-2 key can never exceed its global ceiling even if tier buckets have room.
3. Fail-closed on outage. If the rate-limit store is unreachable, the request is denied with Rate limiting service unavailable. Please retry shortly. rather than silently allowed.

Rate limit denials come back as 422 with an isError: true MCP envelope. Back off and retry.

Troubleshooting

Client reports "no tools" or zero tool count

The key authenticated but the catalog is empty. Causes:

• Autonomy level too low for every tool in the scope. Raise the level or broaden the scopes in Settings -> MCP.
• Key was issued before the AI Agent addon was installed and the agent has since been orphaned. Rare but possible during addon reinstall. Revoke the key and issue a fresh one.

401 Unauthorized

• Missing or malformed Authorization header. Make sure it's Bearer cp_live_..., one space, no quotes.
• Missing X-MCP-Client header. Without it, the request is rejected at 400. Add any short string, e.g. claude-code.
• Key revoked or expired. Check Settings -> MCP - revoked keys stay in the list for audit but cannot be used. Create a new one.

403 Forbidden

• IP not in allowlist. If the key was created with an allowedIps restriction, the request IP must match exactly. Opbox does not accept CIDR ranges - list every IP individually or remove the restriction.
• Workspace suspended. An emergency kill switch, usually billing-driven. Contact support.

503 AI Agent addon is not active

The workspace either never installed the addon, or it's been disabled. Go to Settings -> Addons, find AI Agent, and activate it. Existing keys start working again immediately - no re-issue needed.

422 Autonomy level N cannot invoke "tool_name"

The key's level is below the tool's required level. Either use a different tool at a lower level, or issue a new key at a higher level. Do not raise an existing key's level - create a new key instead, so the audit trail is clean.

422 Rate limit exceeded

Either the tier bucket (300/60/30/10 per minute) or the per-key global ceiling tripped. Slow the caller down, or ask an admin to raise the per-key limit in Settings -> MCP.

Addon tool errors on a specific call only

Four tool families are gated by additional addons: CSP, Equity, Visas, and Accounting. If those addons are not active in the workspace, the tools appear in tools/list (a known cosmetic limitation) but calls fail with The <addon> addon is not enabled for this workspace. Install the relevant addon in Settings -> Addons.

Security notes

• Keys are workspace-scoped. An MCP key can only see data in the workspace where it was issued, even if the owner belongs to multiple workspaces.
• Every call is audited. /api/mcp/tools/call writes an AI_INTEGRATION_EXECUTE entry to the audit log with the tool name, API key ID, and error state. Tool inputs are not recorded, to avoid capturing sensitive arguments.
• Revoke instantly from Settings. Revoked keys stop working on the next request - no cache, no delay. Rotate keys after staff changes or any suspicion of leakage.
• Prefer short expiries. Set a 30-90 day expiry on production keys and rotate. Unattended keys that run "forever" are the most common leakage vector.
• Never commit a key. Store keys in a secrets manager or environment variable - not in a repo, chat history, or config file checked into version control.
• HMAC-hashed at rest. Keys are hashed with HMAC-SHA256 keyed by the platform signing secret, so a database dump alone does not expose usable tokens. Raw keys are never shown after the creation response.
• One key per agent. Create a separate key for each bot, cron job, or workflow so audit trails and revocations stay surgical.