Authentication
Choose the auth option your MCP client supports:- Browser sign-in: configure the MCP URL, sign in to Kapso, and choose one project.
- API key: create a project API key in Kapso and pass it as a header.
Authorization: Bearer for bearer-token clients. Use X-API-Key when your MCP client lets you configure custom headers.
Permissions
When you sign in through the browser, the consent page asks what the agent can do:- Read only (default): read access only. No messages sent, nothing changed.
- Full access: every permission the client requests that your project role allows.
- Custom: search and toggle individual permissions.
Members who are not project owners or admins can’t grant project write, retention read/write, customer or number write/delete, setup link, event write/delete/send, webhook write/delete, broadcast write/send, WhatsApp Flow write/publish, agent write/publish, workflow or function write, team notification, business verification submit, or invitation send/delete permissions. Those permissions are rechecked on every call, so a role downgrade applies immediately.
The agent only sees the tools and actions it has permission for. A call without the required permission returns a tool error with
code: insufficient_scope and the required_scopes. Without setup write access, responses omit setup URLs and tokens. Without webhook write access, they omit webhook secrets and custom headers. Without workflow write access, workflows and workflow_executions responses omit headers.
mcp:broadcasts:write covers creating drafts, managing recipients, stopping a send, and cancelling a schedule. mcp:broadcasts:send covers sending and scheduling. It is separate from mcp:messages:send, so inbox reply access doesn’t allow broadcasts.
Starting or resuming a workflow execution needs both mcp:workflows:run and mcp:messages:send, because the run can send WhatsApp messages. Emitting a project event needs both mcp:events:send and mcp:messages:send, because subscribed workflows can send messages.
mcp:contacts:delete covers contact erasure (deleting a contact and its conversation history). mcp:contacts:write doesn’t include it.
Creating a flow with publish: true also needs mcp:whatsapp_flows:publish. Flow data endpoint actions also need the matching mcp:functions:* permission; update_data_endpoint and register_data_endpoint also need mcp:whatsapp_flows:publish, because they republish published flows. setup_encryption also needs mcp:numbers:write.
The Read only preset doesn’t include mcp:billing:read or mcp:usage:read. Select them, or choose Full access.
Creating or editing a webhook subscribed to project.event also needs mcp:events:read. whatsapp_webhooks list_deliveries omits customer phone numbers unless the connection has mcp:conversations:read.
To change permissions, reconnect and authorize again. The new grant replaces the previous connection for the same app and project, and revokes its tokens. Connections authorized before this change keep full access until you reconnect.
Connect
Browser sign-in
For clients that support browser sign-in, configure only the MCP URL.ChatGPT
Open Kapso in ChatGPT, then ask Open Kapso. Sign in to Kapso, choose a project, and approve its permissions. ChatGPT opens the inbox and the number setup beside the chat. Replies the agent drafts stay as drafts: review or edit them, then send from the inbox.API key
Set your project API key:Use X-API-Key instead
Codex CLI has no--header flag, so X-API-Key goes in ~/.codex/config.toml. For Cursor and Claude Code, just swap the header.
Tools
Project MCP exposes grouped tools. Most tools accept anaction and params.
Use
action: "help" on grouped tools to get required params, optional params, and examples.
whatsapp_webhooks manages both project and number webhooks. Omit the number selector to create a project webhook. project_events create emits an event like POST /platform/v1/events, with the same validation and quotas.
Every tool except findings counts against your plan’s per-minute Platform API rate limit. help calls are free. With an API key, calls share the key’s REST budget. workflow_executions start also follows the per-workflow burst limit of the REST execution endpoint. whatsapp_numbers health shares the REST health check limit of 5 per second and 60 per minute per project. Over a limit, the tool returns an error with code: rate_limited.
Failed calls set isError: true and return error and a code. Common codes are invalid_params, not_found, conflict, forbidden, insufficient_scope, payment_required, rate_limited, unavailable, and upstream_error. Some tools return their own codes, such as ambiguous_identifier from whatsapp_contacts, so treat unknown codes as errors. Rate-limited health calls include details.retry_after in seconds.
Invalid tool arguments also return a tool result with isError: true and code: invalid_params, not a JSON-RPC error. Unknown tools and methods remain JSON-RPC errors.
The server negotiates MCP protocol versions 2025-11-25 (default) and 2025-06-18. Requests with any other MCP-Protocol-Version header return HTTP 400 with JSON-RPC error -32022 listing the supported versions in error.data.supported.
workflow_executions list takes a workflow_id, a whatsapp_conversation_id, or both. list and list_events switch to cursor pagination when you pass limit (1-100, default 20), after, or before, and return paging.next and paging.previous like the REST API. findings list always uses cursors, with limit from 1 to 25 (default 20).
whatsapp_broadcasts mirrors the broadcasts API: create a draft, add recipients in batches of up to 1000, then send or schedule (future ISO-8601 timestamp with a timezone). add_recipients returns added, duplicates, and per-entry errors. Poll get for delivery progress. Recipients return whatsapp_contact_id and whatsapp_conversation_id instead of nested contact and conversation objects.
whatsapp_contacts accepts a contact UUID, phone number, or BSUID as the identifier. An ambiguous BSUID returns ambiguous_identifier with candidate contact IDs; retry with the UUID. update replaces metadata (pass {} to clear it). delete schedules erasure and returns deletion_scheduled: true.
whatsapp_conversation_assignments needs a conversation_id on every call. Use list_members to find a user_id for create. A conversation can have one active assignment: to reassign, update the current one with active: false, then create the new one.
whatsapp_flows mirrors the Platform API for WhatsApp Flows. id is the Kapso flow UUID and version_id is a version UUID. Responses omit data_endpoint_url and preview_url. Publishing is irreversible on Meta. Send flows with whatsapp_messages.
Browser sign-in connections only see the tools and actions their permissions allow.
Retention policy
get_retention_policy returns the saved policy (null when none is configured), plus entitled, minimum_retention_days, and supported presets.
Changing retention takes two calls. First call preview_retention_policy with change_type (update or delete) and retention_days (whole number, or null to keep everything; must be null for delete). It returns the current policy, eligibility counts, a warning, and a preview_token valid for 10 minutes for this user, project, and operation. Show the impact to the user before confirming.
Then call update_retention_policy or delete_retention_policy with preview_token and confirm: true. Tightening the window also needs confirmation set to the project name. Updates need a paid plan (plan_required otherwise). If the policy changed since the preview, the call fails; preview again. An invalid or expired token returns code: invalid_preview, and a preview that runs out of time returns code: preview_timeout.
Tightening takes effect after 48 hours, then history is deleted permanently. Removing the policy keeps future history but doesn’t restore deleted data. Support-suspended policies can’t be removed. get_retention_policy needs mcp:retention:read. Preview also needs mcp:project:read. Update and delete need mcp:retention:write, mcp:retention:read, and mcp:project:read.
Examples
Ask your agent to check setup:Project MCP vs Docs MCP
Use the CLI when your agent has terminal access. Use Project MCP when your agent supports MCP and should operate Kapso directly.

