Developers

Build on Kaption with MCP

Kaption exposes WhatsApp to AI apps and agents through one MCP server. This page lists every endpoint, document and repository you need.

MCP server address

https://mcp.kaptionai.com/mcp

The endpoint

A remote MCP server over Streamable HTTP. It speaks JSON-RPC 2.0 and works with any MCP client that supports OAuth. The tools run in the Kaption extension or desktop app on the user's own computer, so the user must have Kaption open.

Authentication

OAuth 2.1 with PKCE (S256) and dynamic client registration. There is one scope, kaption:access. Users sign in with their phone number and a code sent to them on WhatsApp, then choose how long the connection lasts. Access tokens expire after one hour. Calls without a token get HTTP 401 with a WWW-Authenticate header that points to the protected resource metadata.

Reference

Endpoints and documents

Tools

Tools

The cloud server exposes these tools. From Kaption 0.94, send_message works unless the user has turned off “Let assistants send messages from this computer” in Kaption for that WhatsApp account; an assistant cannot change that setting, and it should still confirm the text and the recipient with the user. It queues a message, with at most one attachment of 8 MiB, to an existing person chat or eligible group for the earliest permitted delivery, and “queued” is not proof of delivery. With the setting off, the AI can leave a draft or schedule one message to one person. Chats the user locked in WhatsApp are never visible.

  • query
  • list_contacts
  • get_contact
  • get_contact_groups
  • list_groups
  • get_group
  • export_contacts
  • download_media
  • get_analytics
  • summarize_conversation
  • manage_chat
  • manage_reminders
  • manage_lists
  • manage_labels
  • manage_notes
  • manage_scheduled_messages
  • send_message
  • call_recordings
Good to know

Limits

  • Tools only work while the user has Kaption open: WhatsApp Web with the extension, or the desktop app.
  • Access is rate-limited. Bulk or unsolicited messaging is against the terms.
  • A scheduled message goes to one person and is at most 800 characters.
  • Sending from this computer is limited to 8 messages an hour and 20 a day, plus group limits and delays, and the computer and WhatsApp must stay open.
Developers

Security

Report vulnerabilities privately to security@kaptionai.com. Please do not open a public issue.

application/problem+json

Errors

Every error the server shapes itself is an RFC 9457 problem document, served as application/problem+json, with type, title, status, detail and a machine-readable code. Branch on code; detail is for people. Errors are never HTML.

Inside the MCP transport (/mcp and /sse), protocol errors are JSON-RPC error objects, as the MCP specification requires, and a failed tool call is a result with isError: true.

StatusCodes
400bad_requestinvalid_jsoninvalid_inputinvalid_content_typeinvalid_phonemissing_credentialsmissing_parametersinvalid_account_idinvalid_connection_idinvalid_authorization_requestinvalid_oauth_stateinvalid_sessionotp_invalidotp_expiredotp_attempts_exceededverification_expiredconnect_code_malformedconnect_code_expired
401unauthorizedauthentication_requiredinvalid_tokenmissing_bearer_tokeninvalid_credentials
403forbidden
404not_foundnot_configuredreviewer_not_configured
405method_not_allowed
406not_acceptable
409conflict
410gone
413payload_too_large
415unsupported_media_type
422unprocessable_content
426upgrade_required
429rate_limited
500internal_errorotp_send_failedauthorization_failed
501not_implemented
502bad_gatewayupstream_errorhandshake_unavailable
503service_unavailable
504gateway_timeout
429 · Retry-After

Rate limits

Throttled requests get 429 with a Retry-After header (seconds) and code rate_limited. Counted responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the policy closest to running out, and RateLimit-Policy lists every policy that applies.

PolicyLimitWindowCounted on
otp-send-account5060 min (fixed)/authorize/send-otp, /ext-auth/send-otp
otp-send-ip10060 min (fixed)/authorize/send-otp, /ext-auth/send-otp, /authorize/resend-otp
otp-resend-account310 min (fixed)/authorize/resend-otp
connect-code-redeem-ip2010 min (restarts on each attempt)/connect/remember, /authorize/connect-code
connect-code-start-account1060 min (restarts on each attempt)/ext/connect-code/start
reviewer-login-ip1015 min (restarts on each attempt)/authorize/reviewer-login

Tool calls have an allowance set by the Kaption plan (https://kaptionai.com/pricing/). Over it, the call is answered with an MCP tool error that links to pricing; the connection stays open, and it is not an HTTP 429. Listing tools, connecting and failed calls do not count. Bulk or unsolicited messaging is still against the terms, and access can be suspended to protect the service.

Deprecation · Sunset

Deprecation and sunset policy

  • Breaking changes to the MCP endpoint, its HTTP contract or a tool are announced on this page at least 90 days before they take effect.
  • Affected responses then carry a Deprecation header (RFC 9745), a Sunset header (RFC 8594) with the date it stops working, and a Link with rel="deprecation" to the migration notes.
  • Adding tools, optional fields or error codes is not a breaking change.

Questions

Is there a REST API?

Kaption's public interface is the MCP server. The OpenAPI file describes that HTTP endpoint so tools that read OpenAPI can find it; the operations themselves are MCP tools called over JSON-RPC.

Can I list the tools without signing in?

No. Every call, including initialize and tools/list, needs a token. The tool names are listed on this page and in the server card.

Which clients work?

Claude, ChatGPT, Cursor and other clients that support remote MCP servers with OAuth. Clients that run local servers can use the npm package instead.

Transcribe one audio now