MCP Tool Surface

The MCP bridge exposes 427 tools across 16 categories. The full per-tool reference lives at the dynamic AI Tools Reference page, which inspects the live registry at request time. This page covers the shape of the surface: categories, gating, and how to think about access control.

Categories

Categories csp, equity, esop, performing-arts-visa, accounting, ai-agent are addon-gated - they appear in tools/list (a known cosmetic limitation) but calls fail with "The <addon> addon is not enabled for this workspace" if the addon is off. Addon membership and a category-to-addon map filter the catalog at assembly time.

Autonomy Tiers in Practice

The full autonomy matrix is in Autonomy Levels. Quick recap:

Read = search, list_*, get_*, agent_queue_list, read-only SQL. Internal Writes = comments, subtasks, step completion, form fills, notification read-state. External Side Effects = call_api_endpoint (GET-only), webhook fires, billable workflow runs. Destructive = bulk operations, delete operations, table schema changes.

Rate Limits per Tier

A per-key bucket sized by autonomy level:

Reads and writes count separately within a level. A level-2 key can burst 300 reads/min without consuming its 30 writes/min.

A second per-key global ceiling layers on top: default 120 req/min, max 1000. The lower of (tier bucket, global ceiling) wins.

Fail-closed on rate-limit-store outage: if the limiter store is unreachable, requests are denied with "Rate limiting service unavailable. Please retry shortly." rather than silently allowed.

What Each Level Unlocks (Practical Examples)

L0 - Read-Only

A surprisingly powerful tier. Common patterns:

• "Find all open matters across our managed clients and tell me which ones are stalling."
• "List documents under the company-formation board that are missing signatures."
• "Run this SQL query to break down spend by client this quarter." (execute_sql is L0 - read-only by construction.)
• "Search system docs for 'autonomy' and summarise."
• Cross-workspace: _targetWorkspaceId reads against subordinate workspaces.

L1 - Internal Writes

Adds writes that don't escape Opbox:

• Add a comment to a matter step.
• Mark notifications read.
• Fill in form fields on a FORM step.
• Complete a step (subject to confirm-then-act in chat; in MCP, the call is direct).
• Claim an AgentTask lease (agent_queue_claim - the doc-gen runtime needs this).

L2 - External Side Effects

Adds writes that are visible outside Opbox:

• call_api_endpoint (GET only - the AI cannot POST/PUT/DELETE through this tool, regardless of level).
• execute_workflow runs a workflow that may send emails or call webhooks.
• run_saved_query may produce side effects depending on the saved query.
• add_line_item updates billing state.

L3 - Destructive + Bulk

Adds operations that need a deliberate intent:

• bulk_create_rows / bulk_update_rows.
• delete_table, delete_column.
• update_document (full structured-JSON replace).
• set_dashboard_config (entire dashboard rewrite).

Cross-Tenant: _targetWorkspaceId

Pass _targetWorkspaceId as a top-level argument on any tool to act on a subordinate workspace. The executor strips it before dispatch (tools never see it).

Authorisation: the calling key's home workspace must hold an ACTIVE oversight relationship over the target, OR the target's org must be managed by the home's super-org. Failures return OVERSEER_TARGET_DENIED and write a security event.

What's preserved across the swap:

• ctx.userId stays the overseer's agent user (audit attribution).
• ctx.autonomyLevel - an L0 overseer key remains read-only against subordinates.
• ctx.apiKeyId - rate-limit budget is the overseer's, not the target's.

Addon gating transitions with the swap: a CSP tool against a target without CSP installed fails at the standard addon gate.

Auth Paths

Two recognised auth paths into /api/mcp/*:

Both paths share the same tool catalogue, the same autonomy enforcement, the same _targetWorkspaceId cross-tenant mechanic, and the same audit trail. The OpenClaw bearer path looks the bearer up by SHA-256 hash on OrganizationAiConfig.openclawBearerHash. See OpenClaw - Bidirectional Auth for details.

cp_live_* keys are recommended when you want fine-grained per-key controls (workspace scoping, per-autonomy-level rate limits, distinct audit identities). The OpenClaw bearer path is recommended when you have one trusted runtime acting on behalf of the org and want a single-secret model.

Audit & Observability

Every MCP tool call writes an AI_INTEGRATION_EXECUTE audit-log entry with:

• apiKeyId (which key)
• workspaceId (the effective workspace - the target after a cross-tenant swap)
• authorityWorkspaceId (set when a swap occurred, otherwise null)
• tool (the tool name)
• result (ok / error / denied)
• Tool inputs are not recorded (avoiding sensitive argument capture).

Surfaced via the standard audit-log endpoints. OWNERs can also query security events directly.

Tool Catalogue Stability

The catalogue's shape (tool names, arg shapes, autonomy levels) is what client integrations depend on. Opbox runs a nightly diff:

1. A boot-time snapshot captures a stable SHA-256 fingerprint of the catalogue per process.
2. /api/cron/tool-catalogue-notify runs daily at 04:00 UTC.
3. If today's fingerprint differs from yesterday's structurally (cosmetic description churn is filtered), all workspace OWNERs get paged.

This means breaking changes to the MCP catalogue are visible day-of, not after a customer's integration breaks.

Errors

All errors come back as MCP { content: [{ type: 'text', text }], isError: true } envelopes.

See Also

• MCP Setup - create a key, wire a client.
• Autonomy Levels - the gating model in detail.
• AI Tools Reference - dynamic per-tool reference.
• Agent Bridge - the canonical MCP-driven agent runtime.