开发者

用 MCP 基于 Kaption 构建

Kaption 通过一个 MCP 服务器把 WhatsApp 开放给 AI 应用和智能体。本页列出你需要的所有端点、文档和代码仓库。

MCP 服务器地址

https://mcp.kaptionai.com/mcp

端点

基于 Streamable HTTP 的远程 MCP 服务器。它使用 JSON-RPC 2.0，适用于任何支持 OAuth 的 MCP 客户端。工具在用户自己电脑上的 Kaption 扩展或桌面应用中运行，因此用户必须打开 Kaption。

身份验证

采用 OAuth 2.1，支持 PKCE（S256）和动态客户端注册。只有一个权限范围：kaption:access。用户用手机号码和通过 WhatsApp 收到的验证码登录，然后选择连接保持多久。访问令牌一小时后过期。不带令牌的调用会收到 HTTP 401，并附带指向受保护资源元数据的 WWW-Authenticate 标头。

参考

端点与文档

工具

工具

云端服务器提供以下工具。从 Kaption 0.94 起，除非用户已在 Kaption 中为该 WhatsApp 账号关闭“允许助手从这台电脑发送消息”，send_message 都可以使用；助手无法更改此设置，并且仍应先和用户确认内容和收件人。它会把一条消息（最多附带一个不超过 8 MiB 的附件）排队发往已有的个人聊天或符合条件的群组，等待最早允许的发送时间；“已排队”并不代表已送达。此设置关闭时，AI 可以留下草稿，或为一个人安排一条定时消息。用户在 WhatsApp 中锁定的聊天永远不可见。

  • 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
须知

限制

  • 只有在用户打开 Kaption 时工具才能工作：装有扩展的 WhatsApp Web，或桌面应用。
  • 访问有频率限制。群发或未经请求的消息违反服务条款。
  • 一条定时消息只能发给一个人，最多 800 个字符。
  • 从这台电脑发送消息每小时最多 8 条、每天最多 20 条，群组另有限制和延迟，并且电脑和 WhatsApp 必须保持打开。
开发者

安全

请将漏洞私下报告至 security@kaptionai.com，不要提交公开 issue。

application/problem+json

错误

服务器自身产生的每个错误都是 RFC 9457 问题文档，以 application/problem+json 返回，包含 type、title、status、detail 和机器可读的 code。请依据 code 判断；detail 供人阅读。错误从不返回 HTML。

在 MCP 传输（/mcp 和 /sse）内部，协议错误按照 MCP 规范为 JSON-RPC 错误对象；工具调用失败时返回 isError: true 的结果。

状态代码
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

速率限制

被限流的请求返回 429，带有 Retry-After 头（秒）和 code rate_limited。计数的响应会带上最接近耗尽的策略的 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset（秒），RateLimit-Policy 列出所有适用的策略。

策略上限时间窗口计数位置
otp-send-account5060 分钟 (固定)/authorize/send-otp, /ext-auth/send-otp
otp-send-ip10060 分钟 (固定)/authorize/send-otp, /ext-auth/send-otp, /authorize/resend-otp
otp-resend-account310 分钟 (固定)/authorize/resend-otp
connect-code-redeem-ip2010 分钟 (每次尝试重新计时)/connect/remember, /authorize/connect-code
connect-code-start-account1060 分钟 (每次尝试重新计时)/ext/connect-code/start
reviewer-login-ip1015 分钟 (每次尝试重新计时)/authorize/reviewer-login

工具调用按 Kaption 套餐限量（https://kaptionai.com/zh/pricing/）。超出后，调用会收到一个附带价格页面链接的 MCP 工具错误；连接保持打开，这不是 HTTP 429。列出工具、建立连接和失败的调用不计入。条款仍禁止群发或未经请求的消息，为保护服务可能暂停访问。

Deprecation · Sunset

弃用与停用政策

  • MCP 端点、其 HTTP 约定或某个工具的不兼容变更，会在生效前至少 90 天在本页公布。
  • 受影响的响应随后会带上 Deprecation 头（RFC 9745）、注明停止日期的 Sunset 头（RFC 8594），以及指向迁移说明的 rel="deprecation" Link。
  • 新增工具、可选字段或错误代码不属于不兼容变更。

常见问题

有 REST API 吗？

Kaption 的公开接口是 MCP 服务器。OpenAPI 文件描述了这个 HTTP 端点，方便读取 OpenAPI 的工具发现它；具体操作是通过 JSON-RPC 调用的 MCP 工具。

不登录能列出工具吗？

不能。每次调用（包括 initialize 和 tools/list）都需要令牌。工具名称已列在本页和服务器卡片中。

支持哪些客户端？

Claude、ChatGPT、Cursor，以及其他支持 OAuth 远程 MCP 服务器的客户端。运行本地服务器的客户端可以改用 npm 软件包。

立即转录一段音频