Kaption AI MCP API

openapi: 3.2.0
info:
  title: Kaption WhatsApp server MCP API
  version: 1.1.0
  summary: Model Context Protocol endpoint that lets AI apps search, summarize and organize a user's WhatsApp chats.
  description: 'This is an MCP server, not a REST API. Every operation is a JSON-RPC 2.0 message sent to one HTTP endpoint (MCP Streamable HTTP transport, protocol revision 2025-06-18 or later). Use an MCP client rather than calling it by hand.


    The tools run in the Kaption extension (WhatsApp Web in Chrome or Edge) or the Kaption desktop app on the user''s own computer, so they only work while the user has Kaption open. No tool sends a message immediately; the AI can leave a draft or schedule one message to one person. Chats the user locked in WhatsApp are never visible.


    Every request, including `initialize` and `tools/list`, needs an OAuth 2.1 bearer token with the `kaption:access` scope. Discover the authorization server through the protected resource metadata (RFC 9728) named in the 401 `WWW-Authenticate` header.


    Errors: every 4xx/5xx the server shapes itself is an RFC 9457 problem document (`application/problem+json`) with a machine-readable `code` (see `Problem`). Inside the MCP transport (`/mcp`, `/sse`), protocol errors are JSON-RPC error objects (see `JsonRpcErrorResponse`). Rate limits, the error codes and the deprecation policy: https://kaptionai.com/developers/#errors'
  termsOfService: https://kaptionai.com/terms/
  contact:
    name: Kaption AI, LLC
    url: https://kaptionai.com/developers/
    email: hey@kaptionai.com
  license:
    name: BUSL-1.1 (relay source)
    url: https://github.com/Kaption-AI/mcp-extension-remote/blob/main/LICENSE
servers:
- url: https://mcp.kaptionai.com
security:
- kaptionOAuth:
  - kaption:access
tags:
- name: MCP
  description: MCP transport endpoints
paths:
  /mcp:
    post:
      tags:
      - MCP
      operationId: mcpMessage
      summary: Send an MCP JSON-RPC message
      description: 'Send one JSON-RPC 2.0 request or notification: `initialize`, `tools/list`, `tools/call`, `ping` and so on. The response is JSON or, for streamed results, an SSE stream. Include the `Mcp-Session-Id` header returned by `initialize` on later requests.'
      parameters:
      - name: Accept
        in: header
        required: true
        schema:
          type: string
          const: application/json, text/event-stream
        description: Must list both application/json and text/event-stream, or the server answers 406.
      - name: Mcp-Session-Id
        in: header
        required: false
        schema:
          type: string
        description: Session ID returned by the server on initialize.
      - name: MCP-Protocol-Version
        in: header
        required: false
        schema:
          type: string
          examples:
          - '2025-06-18'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/JsonRpcRequest'
              - type: array
                items:
                  $ref: '#/components/schemas/JsonRpcRequest'
                minItems: 1
            examples:
              list:
                summary: List tools
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
              call:
                summary: Search messages
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: query
                    arguments:
                      query: invoice
      responses:
        '200':
          description: JSON-RPC response(s), streamed as server-sent events. Each `message` event's data is a `JsonRpcResponse`. The `initialize` answer carries the session ID.
          headers:
            Mcp-Session-Id:
              schema:
                type: string
              description: Returned on initialize; send it on later requests.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseStream'
        '202':
          description: The body held only JSON-RPC notifications or responses. Accepted; the response has no body.
          content:
            text/plain:
              schema:
                type: string
                maxLength: 0
        '400':
          description: 'Invalid JSON-RPC message: parse error (-32700), invalid request (-32600, e.g. a second initialize) or a missing Mcp-Session-Id (-32000).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown or expired MCP session (-32001). Start again with initialize.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '406':
          description: The Accept header does not list both application/json and text/event-stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '413':
          description: Body larger than 4 MiB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '415':
          description: Content-Type is not application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '500':
          description: Internal error (-32001).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
    get:
      tags:
      - MCP
      operationId: mcpStream
      summary: Open a server-to-client SSE stream
      responses:
        '200':
          description: Server-to-client SSE stream of JSON-RPC messages.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseStream'
        '400':
          description: Missing Mcp-Session-Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown or expired MCP session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '406':
          description: Accept does not include text/event-stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
      parameters:
      - name: Mcp-Session-Id
        in: header
        required: true
        schema:
          type: string
        description: Session ID returned by initialize.
      description: Opens a stream for messages the server sends on its own (requests and notifications) within an existing session.
    delete:
      tags:
      - MCP
      operationId: mcpEndSession
      summary: End an MCP session
      responses:
        '204':
          description: Session ended; no body.
        '400':
          description: Missing Mcp-Session-Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown or expired MCP session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
      parameters:
      - name: Mcp-Session-Id
        in: header
        required: true
        schema:
          type: string
      description: Ends the session named by Mcp-Session-Id. Later requests with that ID get 404.
  /sse:
    get:
      tags:
      - MCP
      operationId: legacySse
      summary: Legacy HTTP+SSE transport, for older MCP clients
      responses:
        '200':
          description: 'SSE stream: one `endpoint` event, then `message` events carrying JsonRpcResponse objects.'
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseStream'
        '401':
          $ref: '#/components/responses/Unauthorized'
      description: Opens the legacy transport. The first event is `endpoint`, whose data is the URL to POST messages to (`/sse/message?sessionId=…`); answers then arrive as `message` events.
  /sse/message:
    post:
      tags:
      - MCP
      operationId: legacySseMessage
      summary: Send a JSON-RPC message on the legacy SSE transport
      parameters:
      - name: sessionId
        in: query
        required: true
        schema:
          type: string
        description: From the `endpoint` event of GET /sse.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '202':
          description: Accepted. The literal body `Accepted`; the answer arrives on the GET /sse stream.
          content:
            text/event-stream:
              schema:
                type: string
                const: Accepted
        '400':
          description: Invalid message or missing sessionId (plain text).
          content:
            text/plain:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown session (plain text).
          content:
            text/plain:
              schema:
                type: string
      description: Legacy transport only. POST each JSON-RPC message here; the answer arrives as a `message` event on the GET /sse stream.
components:
  responses:
    Unauthorized:
      description: Missing, expired or invalid bearer token. Follow `resource_metadata` in the `WWW-Authenticate` header to start OAuth.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          example: Bearer realm="OAuth", resource_metadata="https://mcp.kaptionai.com/.well-known/oauth-protected-resource/mcp", scope="kaption:access"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BearerProblem'
  schemas:
    JsonRpcRequest:
      type: object
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          const: '2.0'
        id:
          type:
          - string
          - integer
        method:
          type: string
          examples:
          - initialize
          - tools/list
          - tools/call
        params:
          type: object
          properties:
            name:
              type: string
              description: Tool name, for tools/call.
              enum:
              - 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
            arguments:
              type: object
              description: Tool arguments. Get each tool's input schema from tools/list.
    BearerProblem:
      allOf:
      - $ref: '#/components/schemas/Problem'
      - type: object
        required:
        - error
        - resource_metadata
        properties:
          code:
            enum:
            - authentication_required
            - invalid_token
          error:
            type: string
            enum:
            - invalid_request
            - invalid_token
            - insufficient_scope
            description: RFC 6750 error code, kept for OAuth clients.
          error_description:
            type: string
          resource_metadata:
            type: string
            format: uri
    ToolResult:
      type: object
      required:
      - content
      properties:
        content:
          type: array
          items:
            type: object
            required:
            - type
            properties:
              type:
                type: string
                examples:
                - text
              text:
                type: string
        structuredContent:
          type: object
          properties:
            result: {}
        isError:
          type: boolean
          description: true when the tool failed; the reason is in content.
    SseStream:
      type: string
      contentMediaType: text/event-stream
      description: Server-sent events. The `data` of each `message` event is one JSON-encoded JsonRpcResponse (contentSchema); on GET /mcp it can also be a server request or notification.
      contentSchema:
        $ref: '#/components/schemas/JsonRpcResponse'
    Problem:
      type: object
      description: RFC 9457 problem document. `code` is stable and snake_case; branch on it, not on `title` or `detail`.
      required:
      - type
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri
          examples:
          - https://kaptionai.com/developers/#errors-rate_limited
        title:
          type: string
          examples:
          - Too Many Requests
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        code:
          type: string
          pattern: ^[a-z0-9_]+$
          examples:
          - not_found
          - invalid_token
          - rate_limited
          - internal_error
        policy:
          type: string
          description: 'On 429: the rate-limit policy that ran out.'
        retry_after:
          type: integer
          description: 'On 429: seconds to wait, same as the Retry-After header.'
      additionalProperties: true
    JsonRpcError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          examples:
          - -32700
          - -32600
          - -32000
          - -32001
        message:
          type: string
        data: {}
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      - id
      properties:
        jsonrpc:
          const: '2.0'
        id:
          type:
          - string
          - integer
          - 'null'
        result:
          description: The method's result. For tools/call it is a ToolResult.
          anyOf:
          - $ref: '#/components/schemas/ToolResult'
          - type: object
        error:
          $ref: '#/components/schemas/JsonRpcError'
    JsonRpcErrorResponse:
      type: object
      required:
      - jsonrpc
      - error
      - id
      properties:
        jsonrpc:
          const: '2.0'
        error:
          $ref: '#/components/schemas/JsonRpcError'
        id:
          type:
          - string
          - integer
          - 'null'
  securitySchemes:
    kaptionOAuth:
      type: oauth2
      description: OAuth 2.1 authorization code flow with PKCE (S256) and dynamic client registration at https://mcp.kaptionai.com/register. The user signs in with their phone number and a code sent to them on WhatsApp. Access tokens expire after one hour.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.kaptionai.com/authorize
          tokenUrl: https://mcp.kaptionai.com/token
          refreshUrl: https://mcp.kaptionai.com/token
          scopes:
            kaption:access: Use the Kaption MCP tools on the signed-in user's WhatsApp through Kaption.
externalDocs:
  description: Developer guide
  url: https://kaptionai.com/developers/
x-mcp:
  serverCard: https://kaptionai.com/.well-known/mcp.json
  tools:
  - 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
x-rate-limits:
  documentation: https://kaptionai.com/developers/#rate-limits
  headers:
  - RateLimit-Limit
  - RateLimit-Remaining
  - RateLimit-Reset
  - RateLimit-Policy
  - Retry-After