Skip to main content
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 messaging tools

whatsapp_send_text_message Send text message to existing conversation or recent active conversation by phone. whatsapp_send_template Send template message with parameters. Can start new conversations. whatsapp_send_media Send image, video, audio, or document to existing conversation. whatsapp_send_interactive Send interactive message with buttons or lists. whatsapp_templates List/search approved templates with parameter details.

​
WhatsApp operator tools

whatsapp_inbox View inbox for a host number with last message preview and unread count. whatsapp_get_conversation_context Get conversation metadata and recent messages. Supports batch retrieval. whatsapp_get_contact_context Contact summary with last conversation and recent messages. whatsapp_mark_inbound_read Mark messages as read. whatsapp_configs_overview List host numbers for selection.

​
WhatsApp management tools

whatsapp_search_contacts Search contacts by name or phone. whatsapp_search_conversations Search conversations by phone, name, status, or time. whatsapp_search_messages Search message text. whatsapp_contact_add_note Add note to contact for triage and follow-ups. whatsapp_contact_update Update contact display name or link to customer. whatsapp_conversation_set_status Update conversation status to active or ended.

​
Platform tools

platform_create_customer Create new customer. platform_generate_setup_link Generate branded setup link for customer WhatsApp connection. platform_list_customers List customers with search and pagination. platform_list_customer_configs List WhatsApp configs for a customer. platform_list_setup_links List setup links for a customer with status and expiry. platform_revoke_setup_link Revoke active setup link to invalidate onboarding link.

​
Utility tools

project_info Get current project ID and name.

​
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

​
Troubleshooting

​
”client must accept text/event-stream” or 409 errors

Your MCP server is using SSE transport. Kapso only supports HTTP streamable. Fix: Configure your MCP server to use HTTP streamable transport instead of SSE.

​
Connection test fails with generic “MCP error”

  1. Verify your server uses HTTP streamable (not SSE or stdio)
  2. Test with MCP Inspector
  3. Check server logs for authentication or payload issues

​
Fast MCP returning SSE responses

Fast MCP defaults to SSE. Configure it for HTTP streamable:
  • Remove Content-Type: text/event-stream headers
  • Avoid event: message format in responses