atrium-mcp

A thin, dependency-light MCP server + CLI that proxy the atrium /api/v1 observability surface using an oc_live_ Bearer API key.

It speaks HTTP only — it imports nothing from the Convex app. Each tool maps to one /api/v1 route and one permission, which is enforced server-side by the deployment (requirePermission). A scoped key (e.g. an observer) therefore simply gets a 403 for routes it isn't allowed to call.

Runtime dependencies: @modelcontextprotocol/sdk and zod only.

Configuration (environment)

| Variable | Required | Default | Meaning | | ---------------------------- | -------- | ------------------------ | -------------------------------------------------------- | | OPENCLAW_WEBCHAT_API_BASE | no | http://127.0.0.1:3213 | Deployment .site origin, without /api/v1. | | OPENCLAW_WEBCHAT_API_KEY | yes | — | The oc_live_... Bearer key. |

The /api/v1 prefix is added internally; you point API_BASE at the bare .site origin. The key is only ever sent in the Authorization header — never in a URL/query string and never logged.

Install (released artifact)

Published on every tagged release as @lacneu/atrium-mcp (npm, OIDC + provenance), at the same lockstep version as the app images. Being HTTP-only and provider-neutral, the same package serves any MCP-capable gateway (OpenClaw, Hermes, Claude Code, …).

# ad hoc (any MCP client with stdio command support)
npx -y @lacneu/atrium-mcp

# pinned, baked into a gateway image
npm install -g @lacneu/atrium-mcp@<version>   # provides `atrium-mcp` + `atrium` (CLI)

Example OpenClaw declaration (mcp.servers, stdio) — one server per deployment, credentials injected via a wrapper or the process environment, never in config:

{
  "mcp": {
    "servers": {
      "atrium-prod": { "command": "atrium-mcp-prod" }
    }
  }
}

Build (from source)

cd mcp
npm install
npm run build      # emits dist/ (with shebangs preserved)

Other scripts: npm run typecheck, npm test.

Tools (MCP) / Commands (CLI)

| MCP tool | CLI command | Route | Permission | Purpose | | ---------------------- | ---------------- | ----------------------------- | ------------------ | ------- | | health | health | GET /api/v1/health | none | Liveness probe for the API surface. | | get_compat | compat | GET /api/v1/compat | bridge.read | Bridge version + per-instance gateway versions/capabilities. | | get_integrations | — | GET /api/v1/integrations | traces.read | Opik/Langfuse configured/enabled + shipping cursors. No keys. | | get_chat_state | — | GET /api/v1/chat-state | traces.read | Per-message lifecycle of one chat (metadata only). | | get_trace_enrichment | — | GET /api/v1/trace-enrichment | traces.read | SOC2-safe span structure from Opik/Langfuse, keyed by correlationId. | | diagnose_chat | — | GET /api/v1/diagnose | traces.read | One assessment of a chat + a suggested action/tool. | | reconcile_chat | — | POST /api/v1/reconcile-chat | selfheal | Release a chat's stuck streaming message (text preserved). Audited. | | list_traces | traces | GET /api/v1/traces | traces.read | Recent trace events, with filtering. | | get_kpi | kpi | GET /api/v1/kpi | kpi.read | KPI rollups. | | query_openclaw | query-openclaw | POST /api/v1/openclaw/query | openclaw.query | Query OpenClaw via the bridge. | | list_anomalies | anomalies | GET /api/v1/anomalies | anomalies.read | Detected anomalies, with status/severity/source filtering. | | report_anomaly | report-anomaly | POST /api/v1/anomalies | anomalies.report | Record an anomaly / self-repair signal. |

Tools without a CLI command are MCP-only. Every tool's permission is enforced by the deployment: a key lacking a tool's permission gets a 403 the tool surfaces as an error.

The four read-only diagnostic tools (get_integrations, diagnose_chat, get_chat_state, get_trace_enrichment) plus the bounded corrective reconcile_chat compose into a closed loop an agent can drive from a single user report. See the self-correction loop for how they fit together and the SOC2-safe trace catalog (including the documentary.* document-fetch traces). The whole surface is metadata-only — never message text, filenames, URLs, or keys.

CLI usage

export OPENCLAW_WEBCHAT_API_BASE=http://127.0.0.1:3213
export OPENCLAW_WEBCHAT_API_KEY=oc_live_xxxxxxxxxxxx

node dist/cli.js health
node dist/cli.js compat
node dist/cli.js traces --limit 20
node dist/cli.js traces --kind api.call --correlation-id abc123

# filtering (traces): --q substring, time range, structured fields
#   --from/--to accept epoch ms OR a Grafana relative token (now, now-<N><unit>)
node dist/cli.js traces --from now-24h --to now --status-class 4xx --kind api.call --q foo
node dist/cli.js traces --status 404 --principal-type service --role-key admin

node dist/cli.js kpi --metric api.calls --since 2026-06-01T00:00
node dist/cli.js kpi --metric api.calls --from now-24h --to now
node dist/cli.js anomalies --limit 50 --status open
node dist/cli.js anomalies --from now-1h --severity critical --source detector --q spike
node dist/cli.js query-openclaw --prompt "summarize last run" --chat-id c1
node dist/cli.js report-anomaly --kind latency.spike --severity warn --message "p99 > 5s"

If installed/published, the same is available as the atrium bin (e.g. atrium traces --limit 20).

OpenClaw MCP wiring

Register the stdio server in ~/.openclaw/openclaw.json. Because this package is not published, run the built file directly:

{
  "mcpServers": {
    "atrium": {
      "command": "node",
      "args": ["/absolute/path/to/atrium/mcp/dist/server.js"],
      "env": {
        "OPENCLAW_WEBCHAT_API_BASE": "http://127.0.0.1:3213",
        "OPENCLAW_WEBCHAT_API_KEY": "oc_live_..."
      }
    }
  }
}

After publishing to a registry, the npx form works too:

{
  "mcpServers": {
    "atrium": {
      "command": "npx",
      "args": ["-y", "atrium-mcp"],
      "env": {
        "OPENCLAW_WEBCHAT_API_BASE": "https://<deployment>.convex.site",
        "OPENCLAW_WEBCHAT_API_KEY": "oc_live_..."
      }
    }
  }
}

Security

• The API key lives in env only — never committed, never logged, never in a URL.
• Stdio transport avoids the DNS-rebinding surface of local HTTP MCP servers.
• Permission scoping is enforced by the deployment, not the client: a key that lacks a tool's permission gets a 403 that the tool surfaces as an error.