The MCP server is currently in alpha and subject to changes.
Kapso exposes WhatsApp operations and Platform tools through an MCP server using streamable HTTP transport.
  • Base URL: https://app.kapso.ai/mcp
  • Authentication: Use header X-API-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY
  • Transport: Streamable HTTP only (no SSE)

​
Installation

Replace YOUR_API_KEY with your Kapso project API key.

​
Cursor

Add to ~/.cursor/mcp.json: 
{
  "mcpServers": {
    "kapso": {
      "url": "https://app.kapso.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

​
Claude Code

claude mcp add --transport http kapso https://app.kapso.ai/mcp \
  --header "X-API-Key: YOUR_API_KEY"

​
VS Code

Add to settings.json: 
"mcp": {
  "servers": {
    "kapso": {
      "type": "http",
      "url": "https://app.kapso.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

​
Claude Desktop

Settings → Connectors → Add Custom Connector:
  • Name: Kapso
  • URL: https://app.kapso.ai/mcp
  • Headers: X-API-Key: YOUR_API_KEY

​
Zed

Add to settings.json: 
{
  "context_servers": {
    "Kapso": {
      "type": "http",
      "url": "https://app.kapso.ai/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

​
Available tools

All tool results return JSON serialized as text. Use response_format: "detailed" for stable IDs when needed.

​
WhatsApp operator tools

whatsapp_inbox View inbox for a host number with last message preview and unread count.
  • whatsapp_config_id (required): Host config ID
  • status: active or ended
  • page, limit: Pagination (max 50)
whatsapp_get_conversation_context Get conversation metadata and recent messages. Supports batch retrieval.
  • conversation_id: Single conversation ID
  • conversation_ids: Array of IDs for batch retrieval
  • message_limit: Max 50
  • Note: Provide either conversation_id or conversation_ids, not both
whatsapp_send_message Send text message to existing conversation or phone number.
  • conversation_selector: {conversation_id} or {phone_number}
  • content (required): Message text
  • whatsapp_config_id: Optional specific config to send from
  • allow_start_with_template: Set true if template required for new conversations
  • Returns: Message details including whatsapp_config_used and host_phone
whatsapp_mark_inbound_read Mark messages as read.
  • Single: message_id
  • Bulk: conversation_id + before (ISO8601 timestamp)
whatsapp_get_contact_context Contact summary with last conversation and recent messages.
  • identifier (required): Contact ID or phone number
  • include_recent_messages: Default true
whatsapp_search_contacts Search contacts by name or phone.
  • query (required)
  • customer_id, created_since, created_until: Filters
whatsapp_search_conversations Search conversations by phone, name, status, or time.
  • query, status, whatsapp_config_id: Filters
  • since, until: Time range
  • include_messages: Include recent messages for each conversation (boolean)
  • Note: When include_messages is true, defaults to detailed response format
whatsapp_search_messages Search message text.
  • query (required)
  • conversation_id, since, until: Filters
  • per_hit_context: Context radius (0-5)
whatsapp_configs_overview List host numbers for selection.
  • customer_id: Optional filter

​
Platform tools

platform_create_customer Create new customer.
  • name (required)
  • external_customer_id (required): Must be unique per project
platform_generate_setup_link Generate branded setup link for customer WhatsApp connection.
  • customer_id (required)
  • success_redirect_url, failure_redirect_url: Optional redirects
  • allowed_connection_types: [“coexistence” or “dedicated”]
  • provision_phone_number: Auto-provision new number
platform_list_customers List customers with search.
  • query: Search name or external ID
  • page, limit: Pagination
platform_list_customer_configs List WhatsApp configs for a customer.
  • customer_id (required)
  • page, limit: Pagination

​
Authentication

Include the API key header on every request. Find your API keys in Project Settings → API Keys.

​
Response format

By default, responses are concise to reduce token usage. Use response_format: "detailed" when you need stable IDs for follow-up calls. Smart defaults:
  • whatsapp_get_conversation_context: Defaults to detailed (you’re requesting specific IDs)
  • whatsapp_search_conversations with include_messages: Defaults to detailed (likely need IDs for follow-up)
  • All other tools: Default to concise unless specified