WebKasa MCP & Agent Integrations

How the integration works

The WebKasa HTTP API is the canonical application boundary. The MCP server translates tools and resources into typed HTTP requests; it never connects directly to Supabase or bypasses API-key scopes.

1. Create a least-privilege API key

Create a separate API key for each bot or agent integration in Dashboard → Settings → API Keys. Enable only the scopes that integration needs:

2. Choose an MCP transport

Local agents: stdio

Use stdio when the MCP client and WebKasa MCP run on the same machine. The client starts the process and communicates over standard input and output.

{
  "mcpServers": {
    "webkasa": {
      "command": "pnpm",
      "args": [
        "--dir",
        "/absolute/path/to/webkasa_app/apps/webkasa-mcp",
        "dev"
      ],
      "env": {
        "WEBKASA_BASE_URL": "https://app.webkasa.com",
        "WEBKASA_API_KEY": "wk_live_replace_me"
      }
    }
  }
}

Hosted agents: Streamable HTTP

Use Streamable HTTP when a Discord or Telegram service connects to a separately deployed MCP server. Protect that endpoint with a dedicated bearer token that is different from the WebKasa API key.

WEBKASA_BASE_URL=https://app.webkasa.com
WEBKASA_API_KEY=wk_live_replace_me
WEBKASA_API_TIMEOUT_MS=30000

WEBKASA_MCP_BEARER_TOKEN=replace-with-a-separate-long-random-secret
HOST=0.0.0.0
PORT=3100
WEBKASA_MCP_ALLOWED_HOSTS=mcp.example.com

pnpm --dir apps/webkasa-mcp build
pnpm --dir apps/webkasa-mcp start:http

Connect the MCP client to https://mcp.example.com/mcp with Authorization: Bearer <WEBKASA_MCP_BEARER_TOKEN>. Terminate TLS and apply ordinary request rate limiting at the reverse proxy.

3. Use the MCP tools

4. Understand the HTTP synchronization contract

MCP calls the same versioned HTTP endpoints available to typed API clients. This keeps authorization, validation, organization scoping, and response semantics in one place.

Read organization context

curl "https://app.webkasa.com/api/v1/agent/context" \
  -H "Authorization: Bearer $WEBKASA_API_KEY"

Poll notifications without losing pages

curl "https://app.webkasa.com/api/v1/agent/notifications?since=2026-07-23T12:00:00.000Z&limit=20" \
  -H "Authorization: Bearer $WEBKASA_API_KEY"

# If meta.hasMore is true, request the next page with the opaque cursor:
curl "https://app.webkasa.com/api/v1/agent/notifications?since=2026-07-23T12:00:00.000Z&limit=20&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $WEBKASA_API_KEY"

# After meta.hasMore is false, persist meta.checkpoint_at as the next since value.
# The checkpoint intentionally replays a short overlap; deduplicate by
# notification ID in durable storage across polling runs.

Create an idempotent dashboard update

curl -X POST "https://app.webkasa.com/api/v1/agent/notifications" \
  -H "Authorization: Bearer $WEBKASA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Discord deployment update",
    "message": "Production deployment completed successfully.",
    "source": "discord",
    "external_id": "discord-message-128491",
    "href": "/dashboard/activity",
    "metadata": {
      "channel_id": "123456789",
      "deployment": "production"
    }
  }'

Idempotency is isolated by organization, API key, source, and external ID. Retrying the same message with the same integration key returns the original notification with created: false.

Pull updates now; add push delivery when needed

Production readiness checklist

• Use one least-privilege WebKasa API key per organization and bot.
• Keep the MCP bearer token separate from the outbound WebKasa API key.
• Serve remote MCP only behind TLS and a trusted reverse proxy.
• Set WEBKASA_MCP_ALLOWED_HOSTS when binding outside localhost.
• Use platform message IDs as external_id for every notification write.
• Deduplicate notification IDs in durable storage across polling runs, then persist checkpoint_at only after every cursor page succeeds.
• Log MCP request IDs and platform message IDs, but never raw credentials.
• Rotate both MCP and WebKasa credentials independently.