{
  "openapi": "3.1.0",
  "info": {
    "title": "Kaption WhatsApp MCP server",
    "version": "1.0.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.\n\nThe 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.\n\nEvery 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.",
    "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"
    }
  },
  "externalDocs": {
    "description": "Developer guide",
    "url": "https://kaptionai.com/developers/"
  },
  "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": "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": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "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, or an SSE stream of JSON-RPC messages.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Notification or response accepted; no body."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "get": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpStream",
        "summary": "Open a server-to-client SSE stream",
        "responses": {
          "200": {
            "description": "SSE stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "405": {
            "description": "Streaming not offered on this session."
          }
        }
      },
      "delete": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpEndSession",
        "summary": "End an MCP session",
        "responses": {
          "200": {
            "description": "Session ended."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown session."
          }
        }
      }
    },
    "/sse": {
      "get": {
        "tags": [
          "mcp"
        ],
        "operationId": "legacySse",
        "summary": "Legacy HTTP+SSE transport, for older MCP clients",
        "responses": {
          "200": {
            "description": "SSE stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "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."
            }
          }
        }
      }
    },
    "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/json": {
            "schema": {
              "$ref": "#/components/schemas/OAuthError"
            }
          }
        }
      }
    },
    "schemas": {
      "OAuthError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "invalid_token"
            ]
          },
          "error_description": {
            "type": "string"
          },
          "resource_metadata": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "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",
                  "call_recordings"
                ]
              },
              "arguments": {
                "type": "object",
                "description": "Tool arguments. Get each tool's input schema from tools/list."
              }
            }
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {}
            }
          }
        }
      }
    }
  },
  "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",
      "call_recordings"
    ]
  }
}