Kaption WhatsApp (Cloud)

kaption-mcp-remote

Cloud MCP relay for WhatsApp — lets AI assistants (Claude, ChatGPT, Cursor, etc.) interact with your WhatsApp conversations through the Model Context Protocol.

Setup guide: kaptionai.com/mcp — connect WhatsApp to Claude, ChatGPT or Cursor.

Live at: mcp.kaptionai.com (canonical) and mcp-ext.kaptionai.com (backward-compatible alias for existing connections)

The relay cannot read your messages. It forwards MCP tool calls between the AI client and the Kaption browser extension, which processes everything locally in your browser. Its source code is public (BUSL-1.1), so you can verify it yourself.

Architecture

AI Client (Claude/ChatGPT/Cursor)

│ │ OAuth 2.1 + SSE/Streamable HTTP ▼ ┌─────────────────────────────────────┐ │ Cloudflare Worker │ │ mcp.kaptionai.com │ │ │ │ ┌────────────┐ ┌──────────────┐ │ │ │ OAuthProv │ │ Next.js │ │ │ │ /sse /mcp │ │ /authorize │ │ │ │ /token │ │ /ext-auth │ │ │ │ /register │ │ / (landing) │ │ │ └─────┬──────┘ └──────────────┘ │ │ │ │ │ ┌─────▼──────┐ ┌──────────────┐ │ │ │ RelayMCP │ │ Deployment │ │ │ │ (DO) │ │ ChainDO │ │ │ └─────┬──────┘ └──────────────┘ │ │ │ │ │ ┌─────▼──────┐ │ │ │ RelayRoom │ ◄── WebSocket ──┐ │ │ │ (DO/accountRef) │ │ │ │ └────────────┘ │ │ └─────────────────────────────────┼──┘ │ Browser Extension (WhatsApp Web tab)

Durable Objects

Request Flow

1. AI client discovers the MCP server via /.well-known/oauth-authorization-server
2. Client registers dynamically via POST /register (RFC 7591)
3. User authenticates with WhatsApp OTP at /authorize
4. Client exchanges code for token at /token
5. Client sends tool calls via SSE (/sse) or Streamable HTTP (/mcp)
6. RelayMCP DO receives the call, routes to RelayRoom for the accountRef
7. RelayRoom forwards JSON-RPC to the extension over WebSocket
8. Extension executes in WhatsApp Web context, returns result
9. Result flows back: RelayRoom → RelayMCP → AI client

Routing Table

MCP Tools

26 public tools are forwarded to the extension (the relay does not execute them). Reads and writes are separate tools: every read-only tool carries readOnlyHint: true, and the manage_* tools only write. The read tools for reminders, scheduled messages, chat lists and contact notes reach the extension as the matching manage_* call (TOOL_ROUTES in src/tools.ts), so every Kaption version answers them.

The square brand icon for directory listings and consent screens is served at /brand/kaption-mcp-icon.svg.

get_api_info is local-only and is deliberately excluded from the cloud surface because it returns private REST connection credentials.

Deployment Security

Every deployment is cryptographically signed and recorded in a tamper-evident transparency chain. See SECURITY.md for full details.

Pipeline

GitHub Actions (push to main)

│ ├─ 1. Run tests ├─ 2. Build worker (OpenNext + wrap) ├─ 3. SHA-256 manifest every generated code and asset file ├─ 4. Pre-deploy: Sigstore sign the manifest → Rekor log ├─ 5. Deploy to Cloudflare ├─ 6. Post-deploy: verify hash unchanged, sign attestation → Rekor └─ 7. Append to transparency chain (hash-linked)

Daily heartbeat redeploys (6am UTC) ensure the chain stays active even without code changes.

Deploys are gated — do NOT run wrangler deploy locally

All production deploys go through GitHub Actions. Multiple layers enforce this:

1. wrangler.jsonc is gitignored; scripts/build-config.mjs renders it from wrangler.template.jsonc and refuses to run unless GITHUB_ACTIONS=true + GITHUB_RUN_ID are set (or KAPTIONAI_LOCAL_DEV=1 for dev).
2. npm run predeploy aborts unless those same CI env vars are present.
3. main is branch-protected: requires a reviewed PR + green test, deploy, and verify checks.
4. CODEOWNERS routes every PR through @kshmir.

To ship a change: open a PR → review + CI green → merge to main → Actions builds, signs (Sigstore), deploys, and appends to the transparency chain. npx wrangler deploy from a laptop will fail at step 1 because there is no wrangler.jsonc to deploy.

Verify a Deployment

# 1. Check the transparency chain

curl -s https://mcp.kaptionai.com/transparency/latest | jq .

2. Verify chain integrity

curl -s https://mcp.kaptionai.com/transparency/verify | jq .

3. Verify Sigstore signature (requires cosign)

COMMIT=$(curl -s https://mcp.kaptionai.com/transparency/latest | jq -r '.event.commitSha') cosign verify-blob \ --bundle build-manifest.sigstore.json \ --certificate-identity-regexp "https://github.com/Kaption-AI/mcp-extension-remote/.*" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ build-manifest.json

API Endpoints

Transparency API (public, no auth)

# Full chain history (paginated)

GET /transparency?limit=50&offset=0

Latest deployment

GET /transparency/latest

Verify chain integrity

GET /transparency/verify

MCP (OAuth-protected)

# SSE transport (for Claude Code, Cursor)

GET /sse

Streamable HTTP transport

POST /mcp

Development

# Install dependencies

npm install

Run tests

npm test

Dev server (Next.js only — no Worker routing)

npm run dev

Build the full worker (OpenNext + custom wrapper)

npm run build:worker

Project Structure

src/

index.ts # Worker entry — Hono routing, OAuthProvider composition relay-mcp.ts # RelayMCP Durable Object (McpAgent) relay-room.ts # RelayRoom Durable Object (WebSocket bridge) deployment-chain.ts # DeploymentChainDO (transparency log) otp.ts # OTP generation, verification, JWT, HMAC, rate limiting schemas.ts # Zod schemas for API request validation tools.ts # MCP tool definitions (forwarded, not executed) types.ts # TypeScript interfaces (Env, DeploymentEvent, etc.) app/ page.tsx # Landing page (multilingual, client-side i18n) layout.tsx # Root layout i18n.ts # i18next init (8 languages) locales/ # Translation JSON files authorize/ # OAuth OTP flow pages + API routes ext-auth/ # Extension auth pages + API routes scripts/ wrap-worker.mjs # Post-build: wraps OpenNext output with custom routing

Environment Variables

Vars (wrangler.jsonc)

Secrets (wrangler secret put)

The three OPENAI_* values are also configured as GitHub Actions repository secrets. Add all three together, then run the manual Test, Build & Deploy workflow. CI writes them to an ephemeral mode-0600 file and passes that file to wrangler deploy --secrets-file, so the review configuration ships in the same signed, attested Worker version as the code. The workflow fails closed if only part of the three-value set is present and deletes the temporary file immediately after deployment. Existing Worker