@cailab/mcp

Official Model Context Protocol server for CAI.com: exposes one MCP tool per entry in app/specs/cai-tools.manifest.json and forwards calls to Supabase Edge Functions.

Human-readable policy and workflows: https://cai.com/skill.md.

Requirements

• Node.js 18+
• CAI project Supabase URL + anon key
• CAI User API key (Dashboard) or OAuth access token with appropriate scopes

Install

From the monorepo:

cd packages/cai-mcp && npm install

Or after publish:

npm install -g @cailab/mcp

Environment

| Variable | Required | Description | |----------|----------|-------------| | CAI_SUPABASE_URL or SUPABASE_URL | yes | https://xxx.supabase.co | | CAI_SUPABASE_ANON_KEY or SUPABASE_ANON_KEY | yes | Supabase anon key (apikey header) | | CAI_API_KEY | usually yes | User API key or OAuth access token (Authorization) | | CAI_USER_JWT | optional | Overrides Bearer for api_key_mail tools (mail / send-email); else use CAI_API_KEY with scope mail or full | | CAI_TOOLS_MANIFEST | optional | Path to manifest JSON (default: repo app/specs/cai-tools.manifest.json) |

Security: Never commit keys. Configure secrets in your MCP host (Cursor, Claude Desktop, OpenClaw).

Staging vs production

• CAI_SUPABASE_URL / CAI_SUPABASE_ANON_KEY determine which project receives every tool call. For internal testing, point them at a staging Supabase project; do not mix staging URLs with a production API key (or vice versa).
• Serve the same static paths as app/ on your staging host (/.well-known/agent.json, /specs/cai-tools.manifest.json, /skill.md, /developers.html). Use app/.well-known/agent.staging.example.json as a template for staging Agent Card URLs.
• Runbook: docs/agent/STAGING_ENV_WORKFLOW.md · STAGING_MCP_PRELAUNCH_RUNBOOK.md · static check: STAGING_ORIGIN=https://… bash scripts/staging-static-assets-check.sh

OpenClaw

1. openclaw secrets set CAI_API_KEY "…" (staging key from Dashboard; never paste into chat).
2. Register this server in OpenClaw MCP config with the same env as below (staging Supabase URL + anon key).
3. Point the CAI skill at https://<your-staging-host>/skill.md until sign-off.
4. Confirm with openclaw mcp list, then a read-only call (e.g. get_identity or get_exchange_rate).

Cursor / Claude Desktop

Add to MCP config (stdio):

{
  "mcpServers": {
    "cai": {
      "command": "node",
      "args": ["/absolute/path/to/cai/packages/cai-mcp/src/index.js"],
      "env": {
        "CAI_SUPABASE_URL": "https://YOUR.supabase.co",
        "CAI_SUPABASE_ANON_KEY": "eyJ...",
        "CAI_API_KEY": "cai_..."
      }
    }
  }
}

Tool args

Each tool accepts:

• query — object → URL search params (for GET / some DELETE)
• body — object → JSON body (POST / PUT / PATCH / DELETE)

GAP / partial_live

Tools aligned with docs/agent/API_GAP_REGISTRY.md include gap_id in the MCP description. Treat responses with gap_id or non-200 as honest limits, not bugs.

OAuth authorize

oauth_authorize is browser-only; the MCP tool returns an error explaining to complete OAuth in a browser per skill.md.

Smoke

cd packages/cai-mcp && node scripts/smoke-list-tools.mjs

Verifies the manifest loads and lists registered tool names (no network).