> ## Documentation Index > Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect your BubblaV data to MCP-compatible clients like ChatGPT, Claude Desktop, and OpenClaw. # BubblaV MCP Server The BubblaV MCP (Model Context Protocol) Server enables you to connect your BubblaV data to MCP-compatible clients like **ChatGPT**, **Claude Desktop**, **Google Antigravity**, and **OpenClaw**. This allows your AI agents to search your knowledge base, access analytics, and manage your chatbot's settings — all in real-time. > **Looking for recipes?** For ready-to-use prompts to diagnose content gaps, add knowledge, tune your bot's persona, or set up human handoff, see [Use AI Agents to Manage & Improve Your Chatbot](/user-guide/ai-agent-workflows). ## What Can You Do? * **Search Knowledge Base**: Let your AI agents search your indexed website content * **Manage Knowledge Base**: Add, delete, and list knowledge entries; upload files; sync support tickets; manage crawl URLs and sitemaps * **Access Analytics**: Retrieve full analytics reports programmatically * **Conversation Intelligence**: List, search, and inspect conversations and leads * **Content Gap Analysis**: Identify unanswered questions and knowledge gaps * **Visitor Insights**: Get detailed visitor profiles and activity breakdowns * **Hourly Activity**: Analyze peak support times for staffing optimization * **Scrape Web Pages**: Convert any public URL into markdown with `bubblav_scrape_url` * **Configure the Chatbot**: Read and update the chatbot persona (`custom_instructions`) and website settings * **Design the Widget**: Edit bot name, greetings, suggestions, colors, and position * **Human Handoff**: Create and manage intent triggers that route visitors to a live agent (Pro+) * **Manage Custom Tools**: Create, update, delete, and toggle custom webhook tools for your chatbot (Pro+) * **Manage Forms**: Create and update AI-powered lead-collection forms * **Manage API Keys**: Create, list, and revoke scoped MCP API keys * **Build Automations**: Create custom workflows that leverage your BubblaV data * **Real-time Integration**: Use Server-Sent Events (SSE) for instant data access ## Available Tools > This is a **curated reference** of the most-used tools. A connected client receives the complete, > always-current set via the standard `tools/list` method. ### bubblav\_search\_knowledge Search your indexed knowledge base for relevant content. **Parameters:** * `query` (string, required): Your search query * `limit` (number, optional): Maximum results to return (default: 5, max: 20) **Returns:** ```json theme={null} { "results": [ { "content": "The content snippet...", "source": "https://example.com/page", "title": "Page Title", "relevance": 0.95 } ], "total": 42 } ``` **Example:** ```json theme={null} { "query": "shipping policy", "limit": 10 } ``` ### bubblav\_read\_report Read the full analytics report for your website — the same data shown on the Reports page. **Parameters:** * `date_range` (object, optional): Date range for the report (defaults to current calendar month) * `start` (string): Start date in `yyyy-MM-dd` format * `end` (string): End date in `yyyy-MM-dd` format **Returns:** ```json theme={null} { "totalConversations": 1234, "totalMessages": 4567, "containmentRate": 0.69, "agentTransferRate": 0.31, "avgResponseTime": 12.5, "avgConversationDepth": 4.2, "messageRating": 4.1, "avgConfidenceScore": 0.85, "estimatedCostSavings": 1234.56, "totalLeads": 42, "topCountries": ["US", "GB", "DE"], "mostVisitedLinks": ["https://example.com/pricing"], "previousPeriodComparison": { ... } } ``` **Example:** ```json theme={null} { "date_range": { "start": "2026-03-01", "end": "2026-03-18" } } ``` ### bubblav\_add\_knowledge Add a new text knowledge entry to your knowledge base. The content is automatically split into chunks, queued for embedding, and becomes searchable via `bubblav_search_knowledge` once processed. **Parameters:** * `title` (string, required): Title for this knowledge entry * `content` (string, required): Full text content to index (plain text or Markdown) **Returns:** ```json theme={null} { "id": "uuid-of-new-entry", "title": "Knowledge Entry Title", "chunks_created": 5, "embedding_triggered": true } ``` **Example:** ```json theme={null} { "title": "Shipping Policy", "content": "We ship worldwide. Standard delivery takes 5-7 business days. Express shipping is available for orders over $100." } ``` **Note:** Subject to plan page limits. If your plan limit is reached, you'll receive a `RATE_LIMITED` error. ### bubblav\_scrape\_url Scrape a public web page URL and return markdown content optimized for LLM context. **Parameters:** * `url` (string, required): The page URL to scrape **Returns:** ```json theme={null} { "url": "https://example.com/final-url", "markdown": "# Markdown content..." } ``` **Example:** ```json theme={null} { "url": "https://example.com" } ``` ### bubblav\_list\_conversations List conversations for this website with optional filters. Returns conversation metadata (id, title, state, platform, visitor email/country, rating). **Parameters:** * `status` (string, optional): Filter by conversation state — `"bot"`, `"live_support"`, or `"resolved"` * `platform` (string, optional): Filter by platform (e.g. `"widget"`, `"messenger"`, `"slack"`, `"discord"`, `"whatsapp"`, `"instagram"`) * `date_range` (object, optional): Date range with `start` and `end` in `yyyy-MM-dd` format * `limit` (number, optional): Maximum results (default: 20, max: 100) * `offset` (number, optional): Results to skip for pagination (default: 0) **Example:** ```json theme={null} { "status": "bot", "date_range": { "start": "2026-03-01", "end": "2026-03-31" }, "limit": 10 } ``` ### bubblav\_get\_conversation Get the full details of a single conversation including all messages. Returns conversation metadata plus a chronological list of messages with sender type, content, confidence score, thumbs rating, and response latency. **Parameters:** * `conversation_id` (string, required): UUID of the conversation to retrieve **Example:** ```json theme={null} { "conversation_id": "01234567-89ab-cdef-0123-456789abcdef" } ``` ### bubblav\_search\_conversations Full-text search across all conversation messages. Returns matching message excerpts with surrounding context, conversation metadata, and visitor email if available. **Parameters:** * `query` (string, required): Text to search for in message content (case-insensitive) * `date_range` (object, optional): Date range with `start` and `end` * `limit` (number, optional): Maximum results (default: 20, max: 100) * `offset` (number, optional): Pagination offset (default: 0) **Example:** ```json theme={null} { "query": "billing error", "limit": 10 } ``` ### bubblav\_list\_leads List conversations where the visitor provided their email address (captured leads). Returns email, country, platform, conversation state, and timestamp. **Parameters:** * `platform` (string, optional): Filter by platform * `date_range` (object, optional): Date range * `limit` (number, optional): Maximum results (default: 20, max: 100) * `offset` (number, optional): Pagination offset (default: 0) **Example:** ```json theme={null} { "date_range": { "start": "2026-03-01", "end": "2026-03-31" } } ``` ### bubblav\_list\_unanswered\_questions Find visitor questions that the AI could not answer well — bot replies with low confidence score, fallback responses, or messages rated thumbs-down by the visitor. **Parameters:** * `confidence_threshold` (number, optional): Confidence score cutoff (0.0–1.0, default: 0.5). Replies below this are considered low-quality * `date_range` (object, optional): Date range * `limit` (number, optional): Maximum results (default: 20, max: 100) * `offset` (number, optional): Pagination offset (default: 0) **Example:** ```json theme={null} { "confidence_threshold": 0.3, "limit": 20 } ``` ### bubblav\_get\_most\_asked\_questions Return the most frequently asked visitor questions over a date range (default: last 30 days). Questions are aggregated and deduplicated. **Parameters:** * `date_range` (object, optional): Date range * `limit` (number, optional): Maximum questions (default: 10, max: 50) **Example:** ```json theme={null} { "limit": 20 } ``` ### bubblav\_get\_content\_gaps Return visitor questions that the AI struggled to answer — bot replies with low confidence score or a thumbs-down rating. Use this to prioritise knowledge base improvements. **Parameters:** * `date_range` (object, optional): Date range * `limit` (number, optional): Maximum questions (default: 10, max: 50) **Example:** ```json theme={null} { "limit": 15 } ``` ### bubblav\_get\_answerable\_questions Return AI-generated questions that the chatbot can confidently answer from its knowledge base. Questions are generated and cached automatically when knowledge is indexed. **Parameters:** * `limit` (number, optional): Maximum questions (default: 30, max: 50) **Example:** ```json theme={null} { "limit": 30 } ``` ### bubblav\_delete\_knowledge Delete a text knowledge entry from the knowledge base. Removes the entry and all associated chunks/embeddings. Requires the knowledge entry ID (from `bubblav_list_knowledge_sources`). **Parameters:** * `knowledge_id` (string, required): UUID of the text knowledge entry to delete **Example:** ```json theme={null} { "knowledge_id": "01234567-89ab-cdef-0123-456789abcdef" } ``` ### bubblav\_sync\_ticket\_to\_knowledge Sync a resolved support ticket to the knowledge base. Formats the ticket conversation as a searchable article, splits into chunks, and queues for embedding. Requires Pro plan or higher. **Parameters:** * `ticket_id` (string, required): UUID of the live support ticket to sync **Example:** ```json theme={null} { "ticket_id": "01234567-89ab-cdef-0123-456789abcdef" } ``` ### bubblav\_list\_knowledge\_sources List all knowledge sources for this website. Returns sources from: text entries, Notion pages, Google Docs, Zendesk articles/tickets, and crawled website pages. **Parameters:** None **Example:** ```json theme={null} {} ``` ### bubblav\_get\_visitor\_insights Get insights for a specific visitor including profile data, conversation count, active support tickets, e-commerce orders (Shopify), and subscription status. **Parameters:** * `visitor_id` (string, required): Visitor ID (from conversation data or live support session) **Example:** ```json theme={null} { "visitor_id": "visitor_abc123" } ``` ### bubblav\_get\_hourly\_activity Get hourly activity breakdown showing conversation and support ticket counts per hour (UTC). Returns 24 data points (one per hour), total counts, and peak hour. Defaults to today. **Parameters:** * `date_range` (object, optional): Date range **Example:** ```json theme={null} { "date_range": { "start": "2026-04-05" } } ``` ### bubblav\_list\_tool\_logs Read the audit log of tool calls made for this website — built-in tools and custom webhook tools — to troubleshoot failures. Each entry includes the tool name, succeeded/failed outcome, error message, a truncated result preview, result size, and the request args (with secrets masked). Returns the most recent calls first. **Parameters:** * `limit` (number, required): Maximum number of logs to return (max 200) * `status` (string, optional): Filter by outcome — `succeeded` or `failed`. Omit to return both. * `date_range` (object, optional): Date range (defaults to the last 7 days) * `start` (string): Start date in `yyyy-MM-dd` format * `end` (string): End date in `yyyy-MM-dd` format * `offset` (number, optional): Number of logs to skip for pagination (default: 0) **Returns:** ```json theme={null} { "logs": [ { "id": "uuid", "tool_name": "find_tournaments", "success": false, "error_message": "Request timed out after 5000ms", "created_at": "2026-08-14T12:34:56.000Z", "result_bytes": 0, "result_preview": null, "args": { "city": "Austin" } } ], "total": 1, "limit": 10, "offset": 0, "has_more": false } ``` **Note:** Especially useful for debugging custom webhook tools — ask your AI assistant to pull the failed calls and read the error messages directly. This tool is **not available in the ChatGPT integration**; it works in Claude, Cursor, OpenClaw, and the dashboard. **Example:** ```json theme={null} { "limit": 10, "status": "failed" } ``` ## Custom Tool Management These tools let AI agents create and manage custom webhook tools for your chatbot. For example, you can ask Claude to add a tool that searches for products, looks up inventory, or finds nearby events. Custom tools require a **Pro plan or higher**. ### bubblav\_list\_custom\_tools List all custom webhook tools for this website with their activation status. **Parameters:** None **Returns:** ```json theme={null} { "tools": [ { "id": "uuid", "tool_name": "find_tournaments", "display_name": "Find Tournaments", "description_for_ai": "Search for tournaments near a city...", "endpoint_url": "https://api.example.com/tournaments/search", "authentication_type": "bearer", "http_method": "POST", "argument_schema": { "city": { "type": "string", "description": "City name to search near", "required": true, "method": "query" } }, "is_active": true, "is_active_for_website": true, "has_secret": true, "created_at": "2026-04-01T00:00:00Z", "updated_at": "2026-04-01T00:00:00Z" } ], "total": 1 } ``` **Example:** ```json theme={null} {} ``` ### bubblav\_create\_custom\_tool Create a new custom webhook tool. The tool is activated for the current website by default. **Parameters:** * `tool_name` (string, required): Unique identifier (letters, numbers, underscores, hyphens) * `display_name` (string, required): Human-readable name shown in dashboard * `description_for_ai` (string, required): Instructions for the AI on when and how to use this tool * `description` (string, optional): Short human-readable description shown in dashboard. Auto-generated from `description_for_ai` if omitted. * `endpoint_url` (string, required): Webhook URL the chatbot will call (HTTPS required) * `authentication_type` (string, required): `none`, `bearer`, or `hmac` * `argument_schema` (object, optional): Flat parameter map defining the parameters the tool accepts. Each top-level key must be the real parameter name, and each value may include `type`, `description`, `required`, `default`, and `method` (`query`, `body`, or `path`). Do not wrap it in JSON Schema keys like `type`, `properties`, and `required`. * `http_method` (string, optional): `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` (default: GET) * `activate_for_website` (boolean, optional): Auto-activate for current website (default: true) **Returns:** ```json theme={null} { "id": "uuid-of-new-tool", "tool_name": "find_tournaments", "display_name": "Find Tournaments", "secret_key": "abc123...xyz", "is_active_for_website": true } ``` **Note:** The `secret_key` is only shown once at creation time. Save it immediately. **Example:** ```json theme={null} { "tool_name": "find_tournaments", "display_name": "Find Tournaments", "description_for_ai": "Search for pickleball tournaments near a given city. Use when a visitor asks about upcoming tournaments in their area.", "description": "Searches pickleball tournaments by city and radius", "endpoint_url": "https://api.example.com/tournaments/search", "authentication_type": "bearer", "http_method": "POST", "argument_schema": { "city": { "type": "string", "description": "City name to search near", "required": true, "method": "query" }, "radius_miles": { "type": "number", "description": "Search radius in miles (default: 50)", "default": 50, "method": "query" } } } ``` ### bubblav\_update\_custom\_tool Update an existing custom webhook tool. Only the fields you provide will be changed. **Parameters:** * `tool_id` (string, required): UUID of the tool to update (from `bubblav_list_custom_tools`) * `display_name` (string, optional): New human-readable name * `description_for_ai` (string, optional): New AI instructions * `description` (string, optional): New human-readable description * `endpoint_url` (string, optional): New webhook URL * `authentication_type` (string, optional): `none`, `bearer`, or `hmac` * `argument_schema` (object, optional): New parameter schema * `http_method` (string, optional): New HTTP method * `is_active` (boolean, optional): Enable or disable the tool globally **Example:** ```json theme={null} { "tool_id": "01234567-89ab-cdef-0123-456789abcdef", "description_for_ai": "Updated: Search for tournaments near a city or zip code.", "endpoint_url": "https://api.example.com/v2/tournaments/search" } ``` ### bubblav\_delete\_custom\_tool Permanently delete a custom webhook tool. This removes the tool and deactivates it from all websites. **Cannot be undone.** **Parameters:** * `tool_id` (string, required): UUID of the tool to delete **Example:** ```json theme={null} { "tool_id": "01234567-89ab-cdef-0123-456789abcdef" } ``` ### bubblav\_toggle\_custom\_tool Enable or disable a custom tool for this specific website. Tools must be activated per-website before the chatbot can use them. **Parameters:** * `tool_id` (string, required): UUID of the tool to toggle * `enabled` (boolean, required): `true` to enable, `false` to disable **Example:** ```json theme={null} { "tool_id": "01234567-89ab-cdef-0123-456789abcdef", "enabled": true } ``` ### Custom Tool Authentication When creating a tool, choose an `authentication_type` based on your endpoint's security: | Type | Use Case | Headers Sent | | -------- | ------------------------------- | ----------------------------------------------------------------- | | `none` | Public APIs, testing | None | | `bearer` | APIs with token auth | `Authorization: Bearer ` | | `hmac` | Production APIs, sensitive data | `X-BubblaV-Signature: sha256=` + `X-BubblaV-Timestamp: ` | **Key details:** * A `secret_key` is auto-generated for `bearer` and `hmac` types and returned **only once** at creation time. * For HMAC, the signature is computed as `HMAC-SHA256(secret, ".")`. * Your backend must validate the secret/key on every incoming request. For detailed validation code examples (Node.js, Python), see [Custom Tools → Authentication Methods](/user-guide/integrations/custom-tools#authentication-methods). ## Website & Chatbot Configuration These tools let an AI agent read and change how your chatbot behaves and looks — the same controls as the dashboard's **Settings** and **Design** pages, plus knowledge sources, forms, and API keys. They are what make [agent-driven chatbot management](/user-guide/ai-agent-workflows) possible. ### Chatbot persona & website settings | Tool | Description | Key parameters | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `bubblav_get_website_settings` | Read name, URL, status, crawl discovery mode, allowed domains, and `custom_instructions` (the chatbot persona / system prompt). | none | | `bubblav_update_website_settings` | Update website settings. Set `custom_instructions` to change the chatbot persona (max 2,000 chars). | `custom_instructions`, `website_name`, `discovery_mode` (`auto` / `manual-only` / `sitemap-only`), `allowed_domains`, `allow_all_domains` | ### Widget appearance (Design page) | Tool | Description | Key parameters | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bubblav_get_widget_appearance` | Read bot name, greetings, suggestions, colors, position, product card button labels, branding toggle, and logo/avatar URLs. | none | | `bubblav_update_widget_appearance` | Update widget appearance; only the fields you provide change. | `bot_name`, `greeting_message`, `welcome_message`, `home_screen_title`, `textbox_placeholder`, `chat_suggestions`, `bubble_color`, `primary_color`, `desktop_position`, `mobile_position`, `product_card_view_label`, `product_card_view_detail_label`, `powered_by_visible`, `home_logo_url`, `bot_avatar_url` | > Hiding the "Powered by" branding (`powered_by_visible: false`) requires a paid plan. ### Human-handoff scenarios (Pro+) | Tool | Description | Key parameters | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `bubblav_list_handoff_scenarios` | List handoff trigger scenarios. | none | | `bubblav_create_handoff_scenario` | Create a trigger: when the AI detects the described intent, it hands off to a live agent and shows `response_message`. | `description` (required, max 200), `response_message` (max 500), `is_active` | | `bubblav_update_handoff_scenario` | Update a scenario; only provided fields change. | `scenario_id` (required), `description`, `response_message`, `is_active` | | `bubblav_delete_handoff_scenario` | Permanently delete a scenario. | `scenario_id` (required) | ### Knowledge files & crawl sources | Tool | Description | Key parameters | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `bubblav_upload_knowledge_file` | Upload a file (PDF/DOCX/DOC/TXT/Markdown, ≤10MB) to extract and index. Processing is asynchronous — track with `bubblav_get_crawl_status`. | `filename` (required), `content_type` (required: `pdf`/`docx`/`doc`/`txt`/`md`), `base64_content` (required) | | `bubblav_list_crawl_urls` | List manual crawl URLs, sub-websites, sitemap URLs, and llms.txt URLs. | none | | `bubblav_add_crawl_url` | Add a single public URL to crawl and index, then queue an incremental crawl. | `url` (required) | | `bubblav_delete_crawl_url` | Delete a manual crawl URL by id. | `url_id` (required) | | `bubblav_update_sitemaps` | Replace the sitemap.xml and/or llms.txt URL lists (full replacement arrays). | `sitemap_urls`, `llms_txt_urls` | | `bubblav_get_crawl_status` | Check indexing progress: website status, pages indexed, pending/processing chunk counts. | none | ### Forms | Tool | Description | Key parameters | | --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `bubblav_list_forms` | List AI forms with fields, AI instructions, enabled state, and submission counts. | none | | `bubblav_create_form` | Create an AI-powered form to collect structured data from visitors. | `name` (required), `fields` (required; each needs `id`, `type`, `label`), `ai_instructions`, `enabled` | | `bubblav_update_form` | Update a form; only provided fields change. | `form_id` (required), `name`, `fields`, `ai_instructions`, `enabled` | | `bubblav_delete_form` | Permanently delete a form and its submissions. | `form_id` (required) | ### API keys | Tool | Description | Key parameters | | ------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `bubblav_list_api_keys` | List MCP API keys (name, prefix, scopes, active state, last used). Never returns the secret. | none | | `bubblav_create_api_key` | Create a scoped MCP API key. The full key is returned **only once** — store it immediately. | `name` (required), `scopes` (required: `mcp:read` and/or `mcp:tools:execute`) | | `bubblav_revoke_api_key` | Revoke (deactivate) a key. | `key_id` (required) | ## Setup Guide BubblaV MCP Server supports these connection methods: 1. **ChatGPT** - OAuth 2.0, no API key needed 2. **Claude / Claude Desktop** - OAuth 2.0, no API key needed 3. **Google Antigravity** - OAuth 2.0, no API key needed 4. **API Key** - For OpenClaw and other MCP clients ## Option 1: ChatGPT (OAuth 2.0) Use the same MCP server URL: ``` https://www.bubblav.com/mcp ``` If your client expects an API-style path, this also works: ``` https://www.bubblav.com/api/mcp ``` ChatGPT will start OAuth automatically. Sign in to BubblaV and select the website you want to connect. ## Option 2: Claude (OAuth 2.0) No API key needed. Claude handles authentication automatically via OAuth — just add the server URL. ### Step 1: Add the BubblaV connector In Claude (web or desktop), open **Settings** → **Integrations** (or **Connected tools**) and add a new MCP server with this URL: ``` https://www.bubblav.com/api/mcp ``` ### Step 2: Authorize Claude will open a BubblaV login page. Sign in and select which website to connect. That's it — no config files to edit, no API keys to copy. ## Option 3: OpenClaw (API Key) ### Step 1: Generate an MCP API Key 1. Log in to your BubblaV dashboard at [https://www.bubblav.com](https://www.bubblav.com) 2. Navigate to your **Website Settings** page 3. Click the **API Keys** tab 4. Click **Generate New Key** 5. Enter a name (e.g., "OpenClaw") and select → MCP scopes 6. Click **Generate** and copy the key immediately — it won't be shown again Your API key will look like: ``` bubblav_mcp_a1b2c3d4e5f6g7h8i9j0k1l2 ``` ### Step 2: Configure OpenClaw using mcporter We recommend using [mcporter](https://github.com/jasonacox/mcporter) to easily configure OpenClaw with BubblaV. #### Install mcporter ```bash theme={null} # Using pip pip install mcporter # Or using pipx pipx install mcporter ``` #### Configure BubblaV in OpenClaw Create a configuration file `bubblav.json`: ```json theme={null} { "name": "bubblav", "url": "https://www.bubblav.com/api/mcp", "headers": { "X-API-Key": "bubblav_mcp_YOUR_API_KEY_HERE" } } ``` Then run mcporter: ```bash theme={null} mcporter add bubblav.json ``` #### Manual Configuration If you prefer manual configuration, add this to your OpenClaw config: ```yaml theme={null} name: bubblav connection: url: https://www.bubblav.com/api/mcp headers: X-API-Key: bubblav_mcp_YOUR_API_KEY_HERE ``` ### Step 3: Test the Connection Once connected, your OpenClaw agent will have access to: * `bubblav_search_knowledge` - Search your knowledge base * `bubblav_read_report` - Access full analytics reports * `bubblav_add_knowledge` - Add new knowledge entries * `bubblav_delete_knowledge` - Remove outdated entries * `bubblav_list_knowledge_sources` - List all knowledge sources * `bubblav_list_conversations` - List and filter conversations * `bubblav_get_conversation` - Get full conversation details * `bubblav_search_conversations` - Full-text search across conversations * `bubblav_list_leads` - List captured leads (emails) * `bubblav_list_unanswered_questions` - Find knowledge gaps * `bubblav_get_most_asked_questions` - See trending visitor questions * `bubblav_get_content_gaps` - Identify content improvement areas * `bubblav_get_answerable_questions` - See what your bot can answer * `bubblav_get_visitor_insights` - Get visitor profiles * `bubblav_get_hourly_activity` - Analyze peak support times * `bubblav_sync_ticket_to_knowledge` - Turn resolved tickets into knowledge * `bubblav_scrape_url` - Scrape web pages to markdown * `bubblav_list_custom_tools` - List custom webhook tools * `bubblav_create_custom_tool` - Create a new custom tool * `bubblav_update_custom_tool` - Update an existing custom tool * `bubblav_delete_custom_tool` - Delete a custom tool * `bubblav_toggle_custom_tool` - Enable/disable a tool per-website * `bubblav_list_tool_logs` - Read tool-call logs (status, date range, limit) to debug your custom tools You can test by asking your agent to search for information or add new content to your knowledge base. ## Option 4: OpenClaw (Automatic Setup) ### Setup Everything Automatically Tell OpenClaw to install and configure everything for BubblaV automatically. **Command:** ``` Please configure BubblaV MCP server integration with these details: - Server URL: https://www.bubblav.com/api/mcp - Tools available: bubblav_search_knowledge, bubblav_read_report, bubblav_add_knowledge, bubblav_list_conversations, bubblav_get_conversation, bubblav_search_conversations, bubblav_list_leads, bubblav_list_unanswered_questions, bubblav_get_most_asked_questions, bubblav_get_content_gaps, bubblav_get_answerable_questions, bubblav_delete_knowledge, bubblav_sync_ticket_to_knowledge, bubblav_list_knowledge_sources, bubblav_get_visitor_insights, bubblav_get_hourly_activity, bubblav_scrape_url, bubblav_list_custom_tools, bubblav_create_custom_tool, bubblav_update_custom_tool, bubblav_delete_custom_tool, bubblav_toggle_custom_tool, bubblav_list_tool_logs - Authentication: API key required Please ask me for an MCP API key, or let me guide you through generating one. ``` **What this does:** 1. Opens BubblaV dashboard in your browser 2. Generates an API key with proper scopes 3. Configures OpenClaw with server URL and API key 4. Tests connection **Example prompt:** ``` Setup BubblaV MCP server so I can access my knowledge base and add content to it from OpenClaw. ``` 2. **Search knowledge base**: Ask your AI agent to search your website content 3. **Get analytics**: Request a conversation or performance report 4. **Add knowledge**: Test adding a new knowledge entry with title and content ## Rate Limits MCP API calls are tracked separately from your AI message limits. Each subscription plan includes a monthly MCP call allowance: | Plan | Calls per Month | | ------ | --------------- | | Free | 100 | | Pro | 5,000 | | Custom | Unlimited | **How it works:** * Rolling 30-day window (resets every month from your first call) * When exceeded, you'll receive a `429` status with a `Retry-After` header * Check your usage in the dashboard under **Integrations** → **MCP Settings** ## Security ### Authentication Methods **OAuth 2.0 (Claude):** * Claude handles the full OAuth flow — you only enter the server URL * Uses PKCE (Proof Key for Code Exchange) for enhanced security * Tokens expire after 1 hour (access) or 30 days (refresh) * No credentials to store or rotate **API Key (OpenClaw and other clients):** * Simple authentication via `X-API-Key` header * Keys can be rotated and revoked * Supports scoped permissions ### API Key & Token Management * **Keep your API key secret** - Treat it like a password * **Rotate keys regularly** - Generate new keys and revoke old ones * **Use scopes** - Only grant the permissions you need * **Monitor usage** - Review audit logs regularly ### Scopes Available scopes for MCP API keys and OAuth tokens: * `mcp:read` - Read-only access to your website data * `mcp:tools:execute` - Execute MCP tools and scrape URLs via API ### Audit Logging All MCP tool calls are logged and available in your dashboard: * Tool name and arguments * Success/failure status * API key or OAuth token used * Timestamp View logs at **Chatbot** → **Log** ## Troubleshooting ### Connection Issues **Problem**: "Authentication failed" error **Solutions**: * Verify your API key is correct * Check that the key hasn't been revoked * Ensure the key has the correct scopes * Confirm your account is active **Problem**: "Rate limit exceeded" error **Solutions**: * Check your usage in the dashboard * Wait for the monthly window to reset (check `Retry-After` header) * Consider upgrading your plan for higher limits ### Tool Errors **Problem**: "Unknown tool" error **Solutions**: * Verify you're using the correct tool names * Check that your website has indexed content (for knowledge search) * Ensure your API key has `mcp:tools:execute` scope **Problem**: "Invalid argument" error **Solutions**: * Check that all required parameters are provided * Verify parameter types match the schema * Ensure dates are in ISO format (YYYY-MM-DD) ### Knowledge Base Not Available **Problem**: `bubblav_search_knowledge` tool not available **Solutions**: * Ensure your website has been crawled and content indexed * Check crawl status in the dashboard under **Knowledge Base** * Trigger a new crawl if needed ## Example Use Cases ### Customer Support Agent Create an agent that can search your documentation and provide analytics: ```yaml theme={null} name: support-agent tools: - bubblav_search_knowledge - bubblav_read_report - bubblav_get_conversation - bubblav_get_visitor_insights instructions: | You are a customer support agent with access to our knowledge base. Search for relevant information and provide helpful responses. Look up visitor insights before responding to understand their history. ``` ### Reporting Bot Build a bot that generates monthly performance reports: ```yaml theme={null} name: reporting-bot tools: - bubblav_read_report - bubblav_get_hourly_activity - bubblav_get_most_asked_questions schedule: "0 9 1 * *" # First day of every month at 9 AM instructions: | Generate a performance report for the past month. Include hourly activity breakdowns and top questions. ``` ### Knowledge Search API Create a simple search API for your internal tools: ```javascript theme={null} const response = await fetch('https://www.bubblav.com/api/mcp/call', { method: 'POST', headers: { 'X-API-Key': 'bubblav_mcp_...', 'Content-Type': 'application/json' }, body: JSON.stringify({ toolId: 'bubblav_search_knowledge', arguments: { query: 'return policy', limit: 5 } }) }); const data = await response.json(); ``` ### Knowledge Gap Auto-Filler Build an agent that identifies content gaps and fills them automatically: ```yaml theme={null} name: knowledge-gap-filler tools: - bubblav_get_content_gaps - bubblav_search_knowledge - bubblav_add_knowledge - bubblav_sync_ticket_to_knowledge instructions: | Check for content gaps using bubblav_get_content_gaps. For each gap, search existing knowledge first. If not covered, add a new knowledge entry. Also sync resolved tickets that contain useful answers. ``` ### Custom Tool Manager Let an AI agent manage custom webhook tools for your chatbot: ```yaml theme={null} name: custom-tool-manager tools: - bubblav_list_custom_tools - bubblav_create_custom_tool - bubblav_update_custom_tool - bubblav_delete_custom_tool - bubblav_toggle_custom_tool instructions: | Manage custom webhook tools for the BubblaV chatbot. When asked to create a tool, always list existing tools first to avoid duplicates. Gather the endpoint URL, authentication type, and argument schema from the user. After creating, share the secret_key with the user immediately — it won't be shown again. ``` ### Lead Pipeline Agent Monitor leads and feed them into your CRM: ```yaml theme={null} name: lead-pipeline tools: - bubblav_list_leads - bubblav_get_visitor_insights - bubblav_search_conversations schedule: "0 */6 * * *" # Every 6 hours instructions: | Fetch new leads from the past 6 hours. Enrich each lead with visitor insights. Search their conversations for buying intent signals. ``` ## Support Need help? Contact us at: * **Email**: [support@bubblav.com](mailto:support@bubblav.com) ## API Reference ### Endpoints **MCP (JSON-RPC 2.0):** ``` POST https://www.bubblav.com/api/mcp Headers: Authorization: Bearer (Claude — OAuth) X-API-Key: bubblav_mcp_... (OpenClaw — API key) Content-Type: application/json Body: { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` **OAuth Discovery:** ``` GET https://www.bubblav.com/.well-known/oauth-authorization-server ``` **OAuth Authorize:** ``` GET https://www.bubblav.com/api/oauth/authorize ?response_type=code &client_id= &redirect_uri=https://claude.ai/api/mcp/auth_callback &code_challenge= &code_challenge_method=S256 &state= &scope=claudeai ``` Redirects unauthenticated users to login, then shows a website-selection consent page. **OAuth Token Exchange:** ``` POST https://www.bubblav.com/api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code= &redirect_uri=https://claude.ai/api/mcp/auth_callback &code_verifier= ``` ### Error Codes | Code | Description | | ---- | -------------------------------------------------------- | | 401 | Authentication failed (invalid or missing API key/token) | | 403 | Insufficient scopes | | 429 | Rate limit exceeded | | 500 | Internal server error |