How do I install Kaption WhatsApp (Cloud)?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Kaption WhatsApp (Cloud) need an API key?

No required environment variable is listed on this record.

What transport does Kaption WhatsApp (Cloud) use?

Kaption WhatsApp (Cloud) is reached over HTTP.

When was Kaption WhatsApp (Cloud) last checked?

Last checked 2026-10-16. Use WhatsApp from AI apps through the Kaption extension. OAuth 2.1 relay that cannot read messages.

Kaption WhatsApp (Cloud) MCP server

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

DO	Keyed By	Purpose
RelayMCP	OAuth session	McpAgent — registers tools, relays JSON-RPC to RelayRoom
RelayRoom	Opaque accountRef	WebSocket bridge to extension, auth handshake, request/response matching
DeploymentChainDO	`"main"`	Append-only hash chain for deployment transparency

Request Flow

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

Routing Table

Path	Method	Auth	Handler
`/`	GET	—	Next.js landing page
`/authorize`	GET	—	Next.js OTP form (HMAC-signed oauthReqInfo)
`/authorize/send-otp`	POST	—	Next.js API route → rest-api
`/authorize/verify`	GET/POST	—	Next.js OTP verify → OAuthProvider completeAuthorization
`/authorize/reviewer-login`	POST	Static review credentials	Password completion for the configured synthetic review phone
`/register`	POST	—	OAuthProvider (RFC 7591 dynamic client registration)
`/token`	POST	—	OAuthProvider (token exchange)
`/sse`	GET	OAuth token	RelayMCP DO (SSE transport)
`/mcp`	POST	OAuth token	RelayMCP DO (Streamable HTTP)
`/ws/ext`	GET	JWT/token in auth msg	RelayRoom DO (WebSocket upgrade)
`/ext-auth/*`	Various	—	Next.js extension auth pages + API
`/transparency`	GET	—	DeploymentChainDO (chain history)
`/transparency/latest`	GET	—	DeploymentChainDO (latest entry)
`/transparency/verify`	GET	—	DeploymentChainDO (chain integrity)
`/transparency/gaps`	GET	CF token	Cross-reference CF deploys with chain
`/transparency/append`	POST	DEPLOY_API_KEY	Append entry (CI only)

MCP Tools

16 public tools are forwarded to the extension (the relay does not execute them):

Tool	Description
`query`	Query conversations, contacts, messages, transcriptions, labels, communities, sessions
`summarize_conversation`	Get or generate a conversation summary
`manage_labels`	Add/remove/create/delete WhatsApp Business labels
`manage_notes`	Get/set contact notes (Business accounts)
`download_media`	Download image/video/audio/document from a message
`manage_chat`	Archive, pin, mute, mark read/unread, set/clear draft
`manage_reminders`	Create/list/complete/delete personal reminders
`manage_scheduled_messages`	Schedule messages for future delivery — from Kaption's number (bot, default) or from your own number on this computer (`mode: "local"`, also to groups)
`manage_lists`	Manage personal chat lists (custom categories)
`list_contacts`, `get_contact`, `get_contact_groups`	Read contacts and their group memberships
`list_groups`, `get_group`	Read cached or live group metadata
`export_contacts`	Export contacts as CSV or JSON
`get_analytics`	Analyze WhatsApp activity, rankings, response times, and exports

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:

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).
npm run predeploy aborts unless those same CI env vars are present.
main is branch-protected: requires a reviewed PR + green test, deploy, and verify checks.
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)

Variable	Description
`INTERNAL_API_BASE_URL`	Backend API base URL
`BUILD_HASH`	SHA-256 of worker bundle (set by CI)
`COMMIT_SHA`	Git commit SHA (set by CI)

Secrets (`wrangler secret put`)

Secret	Description
`INTERNAL_API_KEY`	API key for rest-api OTP endpoint
`DEPLOY_API_KEY`	API key for transparency chain append
`JWT_SECRET`	Shared JWT signing secret (same as rest-api, schedule, metadata workers)
`PHONE_REF_SECRET`	HMAC secret used to derive opaque durable account references from phone numbers
`EPHEMERAL_STATE_SECRET`	Encryption secret for short-lived login hints, verify tickets, and encrypted session phone payloads
`OPENAI_APPS_CHALLENGE_TOKEN`	Exact domain-verification token issued by the OpenAI plugin portal
`OPENAI_REVIEW_PASSWORD_SHA256`	Lowercase SHA-256 hex digest of the high-entropy reviewer password
`OPENAI_REVIEW_PHONE`	Phone number used as the dedicated review username and to derive the synthetic account's opaque reference

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 secrets not listed in that file are preserved.

Related Projects

Kaption Extension — Chrome/Edge/Firefox browser extension (the other side of the relay)
@kaptionai/mcp-extension — Local MCP bridge (runs on your machine, no cloud relay)

License

BUSL-1.1

One-time attachment uploads

create_attachment_upload({name,mime,size,target_session?}) is forwarded to the selected Rust core, which checks the owner-only MCP_LOCAL_SEND flag and uses its Kaption JWT to create a same-user upload slot on the schedule Worker. PUT raw bytes to uploadUrl within 15 minutes, then send attachment:{ref:attachmentRef} within one hour. The core consumes the ref once and stores bytes locally for immediate or future scheduled sends. Maximum 8 MiB; existing consent/ask-first limits apply. The relay never reads local files or fetches third-party URLs, and rejects path and url attachment fields.

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)

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

DO	Keyed By	Purpose
RelayMCP	OAuth session	McpAgent — registers tools, relays JSON-RPC to RelayRoom
RelayRoom	Opaque accountRef	WebSocket bridge to extension, auth handshake, request/response matching
DeploymentChainDO	`"main"`	Append-only hash chain for deployment transparency

Request Flow

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

Routing Table

Path	Method	Auth	Handler
`/`	GET	—	Next.js landing page
`/authorize`	GET	—	Next.js OTP form (HMAC-signed oauthReqInfo)
`/authorize/send-otp`	POST	—	Next.js API route → rest-api
`/authorize/verify`	GET/POST	—	Next.js OTP verify → OAuthProvider completeAuthorization
`/authorize/reviewer-login`	POST	Static review credentials	Password completion for the configured synthetic review phone
`/register`	POST	—	OAuthProvider (RFC 7591 dynamic client registration)
`/token`	POST	—	OAuthProvider (token exchange)
`/sse`	GET	OAuth token	RelayMCP DO (SSE transport)
`/mcp`	POST	OAuth token	RelayMCP DO (Streamable HTTP)
`/ws/ext`	GET	JWT/token in auth msg	RelayRoom DO (WebSocket upgrade)
`/ext-auth/*`	Various	—	Next.js extension auth pages + API
`/transparency`	GET	—	DeploymentChainDO (chain history)
`/transparency/latest`	GET	—	DeploymentChainDO (latest entry)
`/transparency/verify`	GET	—	DeploymentChainDO (chain integrity)
`/transparency/gaps`	GET	CF token	Cross-reference CF deploys with chain
`/transparency/append`	POST	DEPLOY_API_KEY	Append entry (CI only)

MCP Tools

16 public tools are forwarded to the extension (the relay does not execute them):

Tool	Description
`query`	Query conversations, contacts, messages, transcriptions, labels, communities, sessions
`summarize_conversation`	Get or generate a conversation summary
`manage_labels`	Add/remove/create/delete WhatsApp Business labels
`manage_notes`	Get/set contact notes (Business accounts)
`download_media`	Download image/video/audio/document from a message
`manage_chat`	Archive, pin, mute, mark read/unread, set/clear draft
`manage_reminders`	Create/list/complete/delete personal reminders
`manage_scheduled_messages`	Schedule messages for future delivery — from Kaption's number (bot, default) or from your own number on this computer (`mode: "local"`, also to groups)
`manage_lists`	Manage personal chat lists (custom categories)
`list_contacts`, `get_contact`, `get_contact_groups`	Read contacts and their group memberships
`list_groups`, `get_group`	Read cached or live group metadata
`export_contacts`	Export contacts as CSV or JSON
`get_analytics`	Analyze WhatsApp activity, rankings, response times, and exports

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:

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).
npm run predeploy aborts unless those same CI env vars are present.
main is branch-protected: requires a reviewed PR + green test, deploy, and verify checks.
CODEOWNERS routes every PR through @kshmir.

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)

Variable	Description
`INTERNAL_API_BASE_URL`	Backend API base URL
`BUILD_HASH`	SHA-256 of worker bundle (set by CI)
`COMMIT_SHA`	Git commit SHA (set by CI)

Secrets (`wrangler secret put`)

Secret	Description
`INTERNAL_API_KEY`	API key for rest-api OTP endpoint
`DEPLOY_API_KEY`	API key for transparency chain append
`JWT_SECRET`	Shared JWT signing secret (same as rest-api, schedule, metadata workers)
`PHONE_REF_SECRET`	HMAC secret used to derive opaque durable account references from phone numbers
`EPHEMERAL_STATE_SECRET`	Encryption secret for short-lived login hints, verify tickets, and encrypted session phone payloads
`OPENAI_APPS_CHALLENGE_TOKEN`	Exact domain-verification token issued by the OpenAI plugin portal
`OPENAI_REVIEW_PASSWORD_SHA256`	Lowercase SHA-256 hex digest of the high-entropy reviewer password
`OPENAI_REVIEW_PHONE`	Phone number used as the dedicated review username and to derive the synthetic account's opaque reference

Related Projects

Kaption Extension — Chrome/Edge/Firefox browser extension (the other side of the relay)
@kaptionai/mcp-extension — Local MCP bridge (runs on your machine, no cloud relay)

License

BUSL-1.1

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

kaption-mcp-remote

Architecture

Durable Objects

Request Flow

Routing Table

MCP Tools

Deployment Security

Pipeline

Deploys are gated — do NOT run wrangler deploy locally

Verify a Deployment

API Endpoints

Transparency API (public, no auth)

MCP (OAuth-protected)

Development

Project Structure

Environment Variables

Vars (wrangler.jsonc)

Secrets (wrangler secret put)

Related Projects

License

One-time attachment uploads

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

kaption-mcp-remote

Architecture

Durable Objects

Request Flow

Routing Table

MCP Tools

Deployment Security

Pipeline

Deploys are gated — do NOT run wrangler deploy locally

Verify a Deployment

API Endpoints

Transparency API (public, no auth)

MCP (OAuth-protected)

Development

Project Structure

Environment Variables

Vars (wrangler.jsonc)

Secrets (wrangler secret put)

Related Projects

License

One-time attachment uploads

Deploys are gated — do NOT run `wrangler deploy` locally

Secrets (`wrangler secret put`)

Deploys are gated — do NOT run `wrangler deploy` locally

Secrets (`wrangler secret put`)