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.

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, position, and the Help Center tab
Manage the Help Center: Create, update, reorder, and delete Help Center groups and articles
Human Handoff: Build intent-triggered flows 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 Flows: Create, update, and inspect visual multi-step chatbot scenarios (Pro+)
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:

{
  "results": [
    {
      "content": "The content snippet...",
      "source": "https://example.com/page",
      "title": "Page Title",
      "relevance": 0.95
    }
  ],
  "total": 42
}

Example:

{
  "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. Must not be in the future or after end.
- end (string): End date in yyyy-MM-dd format (defaults to today)

Returns (abridged):

{
  "period": { "start": "2026-03-01", "end": "2026-03-18" },
  "metrics": {
    "total_conversations": 1234,
    "total_messages": 4567,
    "total_leads": 42,
    "containment_rate": 69,
    "resolution_rate": 72,
    "agent_transfer_rate": 31,
    "avg_response_time_ms": 2830,
    "avg_messages_per_conversation": 4.2,
    "estimated_cost_savings": 6816,
    "estimated_cost_savings_currency": "USD"
  },
  "top_countries": [{ "country": "US", "conversation_count": 50 }],
  "most_visited_links": [{ "url": "https://example.com/pricing", "text": "Pricing", "clicks": 9 }],
  "comparison": { "total_conversations": 1100, "containment_rate": 65 }
}

Rates are percentages, and they are null when the period has no conversations. Estimated cost savings are in USD: $8 for each conversation the AI resolved without a human. Example:

{
  "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:

{
  "id": "uuid-of-new-entry",
  "title": "Knowledge Entry Title",
  "chunks_created": 5,
  "embedding_triggered": true
}

Example:

{
  "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:

{
  "url": "https://example.com/final-url",
  "markdown": "# Markdown content..."
}

Example:

{
  "url": "https://example.com"
}

Note: This tool is not available in the ChatGPT or Muse integrations; it works in Claude, Cursor, OpenClaw, and the dashboard. Use bubblav_add_crawl_url, bubblav_upload_knowledge_file, or bubblav_add_knowledge to add content instead.

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:

{
  "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:

{
  "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:

{
  "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. Note: This tool is not available in the ChatGPT or Muse integrations; it works in Claude, Cursor, OpenClaw, and the dashboard. 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{}

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. Note: This tool is not available in the ChatGPT or Muse integrations; it works in Claude, Cursor, OpenClaw, and the dashboard. Parameters:

visitor_id (string, required): Visitor ID (from conversation data or live support session)

Example:

{
  "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:

{
  "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:

{
  "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 or Muse integrations; it works in Claude, Cursor, OpenClaw, and the dashboard. Example:

{
  "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:

{
  "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:

{}

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 <secret_key>`
`hmac`	Production APIs, sensitive data	`X-BubblaV-Signature: sha256=<sig>` + `X-BubblaV-Timestamp: <ms>`

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, "<timestamp>.<compact_json_body>").
Your backend must validate the secret/key on every incoming request.

For detailed validation code examples (Node.js, Python), see 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 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 5,000 chars; an empty string leaves it unchanged, `clear_custom_instructions: true` removes it; `{{botName}}`, `{{websiteName}}`, `{{websiteDescription}}` placeholders resolve at chat time).	`custom_instructions`, `clear_custom_instructions`, `website_name`, `website_url` (re-points crawling + domain verification; normalized to https), `discovery_mode` (`auto` / `manual-only` / `sitemap-only`), `allowed_domains`, `allow_all_domains`

Tool	Description	Key parameters
`bubblav_get_widget_appearance`	Read bot name, greetings, suggestions, colors, position, product card button labels, branding toggle, logo/avatar URLs, avatar shape, widget language, Home/Messages tab labels, Help Center tab toggle and label, launcher style/icon/label and colors, greeting bubble toggle, AI disclosure label, disclaimer, file upload toggle, and center pill colors.	none
`bubblav_update_widget_appearance`	Update widget appearance; only the fields you provide change.	`bot_name`, `greeting_message`, `welcome_message`, `home_screen_title`, `home_introduction_text`, `start_conversation_text`, `textbox_placeholder`, `chat_suggestions`, `bubble_color`, `bubble_icon_color` (launcher icon + label text), `primary_color`, `desktop_position` / `mobile_position` (`bottom-right`, `bottom-left`, or `bottom-center`), `show_greeting_message`, `show_ai_disclosure`, `ai_disclosure_text` (max 40 chars; empty string resets to the default), `disclaimer_text` (max 300 chars; shown under the message input in the chat and on the AI Page; empty string removes it), `file_upload_enabled` (boolean; lets visitors attach files in the chat composer, off by default), `center_pill_bg_color`, `center_pill_text_color`, `center_pill_icon_color`, `center_pill_border_color` (hex or `transparent`), `product_card_view_label`, `product_card_view_detail_label`, `powered_by_visible`, `home_logo_url`, `bot_avatar_url`, `avatar_shape` (`circle` or `square`), `widget_language` (`auto`, `en`, `sv`, `tr`, `nb`, `vi`, `nl`, `es`, `de`, `pt`; built-in UI language, with `nb` for Norwegian Bokmål), `home_tab_label`, `messages_tab_label` (also sets the Messages screen title), `show_help_center_tab` (boolean; shows the Help Center footer tab), `help_center_tab_label` (max 80 chars; empty string resets to the translated default “Help”), `launcher_style` (`bubble` or `labeled`), `launcher_icon` (`chat`, `message`, `book`, `sparkles`, `help`, `headset`, `bot`, or `none`; `none` applies to `labeled` only), `launcher_label` (max 30 chars; empty string resets to the default “Ask assistant”)

Hiding the “Powered by” branding (powered_by_visible: false) requires a paid plan.

These tools manage the search box (search.js), a separate product from the chat widget.

Tool	Description	Key parameters
`bubblav_get_search_widget_config`	Read the search box settings: AI overview on/off, mode, theme, placeholder, result count, shortcut hint, suggested searches, and sizes.	none
`bubblav_update_search_widget_config`	Update the search box settings; only the fields you provide change. Set `ai_enabled: false` to show only instant keyword and semantic results (no AI overview, no message quota used).	`ai_enabled`, `default_mode` (`icon` / `compact` / `full`), `theme` (`light` / `dark`), `placeholder_text` (max 100 chars), `result_limit` (`3` / `5` / `10`), `show_shortcut`, `suggested_queries` (max 10), `icon_size`, `compact_width`, `compact_height`
`bubblav_get_search_widget_snippet`	Get the container `<div>` and `<script>` tag that add the search box to a website.	`element_id` (optional, default `bubblav-search`)

Each AI search uses one message from the plan quota. Changes apply to the live search box within about a minute.

Human handoff (Pro+)

Handoffs are flows: a visitor_intent trigger describing when to escalate (e.g. “wants to speak to sales”), followed by a request_human node that opens a live-support ticket. Build them with the flow tools below — see Human Handoff.

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, or add a file the user attached in the Ask BubblaV assistant (dashboard help panel). Processing is asynchronous — track with `bubblav_get_crawl_status`.	Exactly one of: `attachment_id` (id of an Ask BubblaV attachment; preferred for attached files), or `base64_content` with `filename` and `content_type` (`pdf`/`docx`/`doc`/`txt`/`md`)
`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)

Help Center

These tools manage the content of the Help Center tab: groups (one folder level, no nesting) and articles. Only published content shows in the widget. A draft group hides its articles. Turn the tab on with show_help_center_tab in bubblav_update_widget_appearance. Call bubblav_get_help_center first to get the ids the other tools need.

Tool	Description	Key parameters
`bubblav_get_help_center`	Read all groups and articles, including drafts, in display order, with their ids. Read-only.	none
`bubblav_create_help_center_group`	Create a group. It goes to the end of the list.	`title` (required, max 80 chars), `status` (`draft` or `published`; default `published`)
`bubblav_update_help_center_group`	Rename a group, or publish or unpublish it; only provided fields change. Status `draft` hides the group and its articles from the widget.	`group_id` (required), `title`, `status`
`bubblav_delete_help_center_group`	Destructive. Permanently delete a group and all articles inside it. Cannot be undone. To keep the articles, move them first with `bubblav_update_help_center_article`, or unpublish the group.	`group_id` (required)
`bubblav_create_help_center_article`	Create an article. It goes to the end of its group, or of the top level.	`title` (required, max 200 chars), `type` (`text` or `link`; default `text`), `content_md` (markdown, max 50,000 chars; required for `text`), `url` (`http(s)`, max 2,048 chars; required for `link`; opens in a new tab), `group_id` (omit or `null` for the top level), `status` (`draft` or `published`; default `published`)
`bubblav_update_help_center_article`	Update an article; only provided fields change. The result is validated as a whole, so switching `type` needs the matching `url` or `content_md`. Changing `group_id` moves the article to the end of the new group (`null` = top level).	`article_id` (required), `title`, `type`, `content_md`, `url`, `group_id`, `status`
`bubblav_delete_help_center_article`	Destructive. Permanently delete an article. Cannot be undone. Set `status` to `draft` with `bubblav_update_help_center_article` to hide it instead.	`article_id` (required)
`bubblav_reorder_help_center`	Set the display order of groups, or of articles. Use `kind: "group"` with all group ids in the new order. Use `kind: "article"` with the ids of articles that share the same group, or of all top-level articles.	`kind` (required: `group` or `article`), `ids` (required: array of UUIDs in the desired order)

The two delete tools are destructive. MCP clients that honor tool annotations, and Ask BubblaV, ask for your approval before they run.

Flows (Pro+)

Tool	Description	Key parameters
`bubblav_list_flows`	List flows with name, trigger type, active state, and run counts.	none
`bubblav_get_flow`	Get a single flow including its full `definition` (`nodes` + `edges`).	`flow_id` (required)
`bubblav_create_flow`	Create a flow. The `definition` is validated (exactly one trigger, acyclic, all nodes reachable). A `form_submitted` trigger accepts optional `data.formId` to pin the flow to one form (ids via `bubblav_list_forms`); omit it to fire on every submission. New flows are inactive — tell the user to test in the editor before activating. Not available in the ChatGPT or Muse integrations.	`name` (required), `definition` (required: `{nodes, edges}`), `description`, `is_active`
`bubblav_update_flow`	Update a flow; only provided fields change. `definition` is re-validated. Not available in the ChatGPT or Muse integrations.	`flow_id` (required), `name`, `description`, `definition`, `is_active`
`bubblav_delete_flow`	Permanently delete a flow and its run history.	`flow_id` (required)
`bubblav_list_flow_runs`	List execution runs for a flow (status, trigger event, timestamps). Not available in the ChatGPT or Muse integrations — runs carry visitor form submissions.	`flow_id` (required), `limit`, `offset`

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. Not available in the ChatGPT or Muse integrations.	none
`bubblav_create_api_key`	Create a scoped MCP API key. The full key is returned only once — store it immediately. Not available in the ChatGPT or Muse integrations.	`name` (required), `scopes` (required: `mcp:read` and/or `mcp:tools:execute`)
`bubblav_revoke_api_key`	Revoke (deactivate) a key. Not available in the ChatGPT or Muse integrations.	`key_id` (required)

Setup Guide

BubblaV MCP Server supports these connection methods:

ChatGPT - OAuth 2.0, no API key needed
Claude (claude.ai, Desktop, Cowork, Claude Code) - OAuth 2.0, no API key needed
Cursor - OAuth 2.0, no API key needed
Meta Muse - OAuth 2.0, no API key needed
Google Antigravity - OAuth 2.0, no API key needed
API Key - For OpenClaw and other MCP clients

OAuth details

Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Dynamic client registration (RFC 7591) and client ID metadata documents are supported.
PKCE: send code_challenge with code_challenge_method=S256. When the authorization request has a challenge, the token request must send the matching code_verifier. The plain method is rejected.
Access level: on the consent screen the user picks Full access or Read only. Full access grants the mcp:read and mcp:tools:execute scopes. Read only grants only mcp:read: tools/list returns only the tools with readOnlyHint: true, and calling any other tool returns an error. A client that requests scope=mcp:read gets Read only preselected.
Revoking: each connection is an API key named after the client (for example ChatGPT, Claude, Muse). Revoke it under Settings → API Keys in the dashboard to disconnect.

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. In Claude, open Customize → Connectors and search the directory for BubblaV, or select + → Add custom connector and enter:

https://www.bubblav.com/mcp

Claude opens a BubblaV login page. Sign in and select which website to connect. In Claude Code, install the plugin with /plugin marketplace add bubblav-org/bubblav-claude and /plugin install bubblav@bubblav. Full steps: Claude.

Cursor (OAuth 2.0)

Install the BubblaV plugin from the Cursor Marketplace, or add https://www.bubblav.com/mcp as a server in mcp.json. Cursor starts OAuth when the agent first calls a BubblaV tool. Full steps: Cursor.

Meta Muse (OAuth 2.0)

In Muse, open Settings → Connectors and connect BubblaV. Muse opens a BubblaV login page. Sign in, select which website to connect, and choose Full access or Read only. Full steps and the tool list with read/write classes: Muse.

Option 3: OpenClaw (API Key)

Step 1: Generate an MCP API Key

Log in to your BubblaV dashboard at https://www.bubblav.com
Navigate to your Website Settings page
Click the API Keys tab
Click Generate New Key
Enter a name (e.g., “OpenClaw”) and select → MCP scopes
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 to easily configure OpenClaw with BubblaV.

Install mcporter

# Using pip
pip install mcporter

# Or using pipx
pipx install mcporter

Configure BubblaV in OpenClaw

Create a configuration file bubblav.json:

{
  "name": "bubblav",
  "url": "https://www.bubblav.com/api/mcp",
  "headers": {
    "X-API-Key": "bubblav_mcp_YOUR_API_KEY_HERE"
  }
}

Then run mcporter:

mcporter add bubblav.json

Manual Configuration

If you prefer manual configuration, add this to your OpenClaw config:

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:

Opens BubblaV dashboard in your browser
Generates an API key with proper scopes
Configures OpenClaw with server URL and API key
Tests connection

Example prompt:

Setup BubblaV MCP server so I can access my knowledge base and add content to it from OpenClaw.

Search knowledge base: Ask your AI agent to search your website content
Get analytics: Request a conversation or performance report
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:

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:

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:

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:

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:

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:

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

API Reference

Endpoints

MCP (JSON-RPC 2.0):

POST https://www.bubblav.com/api/mcp
Headers:
  Authorization: Bearer <oauth-token>   (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=<client_id>
  &redirect_uri=https://claude.ai/api/mcp/auth_callback
  &code_challenge=<PKCE challenge>
  &code_challenge_method=S256
  &state=<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=<authorization code>
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&code_verifier=<PKCE verifier>

Error Codes

Code	Description
400	Invalid request or tool arguments (JSON-RPC `-32602`)
401	Authentication failed (invalid or missing API key/token)
403	Insufficient scopes. On `POST /api/mcp/call`, also `PLAN_REQUIRED`: the tool needs a higher plan
429	Rate limit exceeded
500	Internal server error

On the JSON-RPC endpoint (POST /api/mcp), a tools/call that a plan, usage limit, or admin-only gate blocks returns HTTP 200 with a tool result that has isError: true. The content text tells the user what to do, for example “Flows require a Pro plan or higher”.

​BubblaV MCP Server

​What Can You Do?

​Available Tools

​bubblav_search_knowledge

​bubblav_read_report

​bubblav_add_knowledge

​bubblav_scrape_url

​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_list_tool_logs

​Custom Tool Management

​bubblav_list_custom_tools

​bubblav_create_custom_tool

​bubblav_update_custom_tool

​bubblav_delete_custom_tool

​bubblav_toggle_custom_tool

​Custom Tool Authentication

​Website & Chatbot Configuration

​Chatbot persona & website settings

​Widget appearance (Design page)

​AI search widget (Search page)

​Human handoff (Pro+)

​Knowledge files & crawl sources

​Forms

​Help Center

​Flows (Pro+)

​API keys

​Setup Guide

​OAuth details

​Option 1: ChatGPT (OAuth 2.0)

​Option 2: Claude (OAuth 2.0)

​Cursor (OAuth 2.0)

​Meta Muse (OAuth 2.0)

​Option 3: OpenClaw (API Key)

​Step 1: Generate an MCP API Key

​Step 2: Configure OpenClaw using mcporter

​Install mcporter

​Configure BubblaV in OpenClaw

​Manual Configuration

​Step 3: Test the Connection

​Option 4: OpenClaw (Automatic Setup)

​Setup Everything Automatically

​Rate Limits

​Security

​Authentication Methods

​API Key & Token Management

​Scopes

​Audit Logging

​Troubleshooting

​Connection Issues

​Tool Errors

​Knowledge Base Not Available

​Example Use Cases

​Customer Support Agent

​Reporting Bot

​Knowledge Search API

​Knowledge Gap Auto-Filler

​Custom Tool Manager

​Lead Pipeline Agent

​Support

​API Reference

​Endpoints

​Error Codes

BubblaV MCP Server

What Can You Do?

Available Tools

bubblav_search_knowledge

bubblav_read_report

bubblav_add_knowledge

bubblav_scrape_url

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_list_tool_logs

Custom Tool Management

bubblav_list_custom_tools

bubblav_create_custom_tool

bubblav_update_custom_tool

bubblav_delete_custom_tool

bubblav_toggle_custom_tool

Custom Tool Authentication

Website & Chatbot Configuration

Chatbot persona & website settings

Widget appearance (Design page)

AI search widget (Search page)

Human handoff (Pro+)

Knowledge files & crawl sources

Forms

Help Center

Flows (Pro+)

API keys

Setup Guide

OAuth details

Option 1: ChatGPT (OAuth 2.0)

Option 2: Claude (OAuth 2.0)

Cursor (OAuth 2.0)

Meta Muse (OAuth 2.0)

Option 3: OpenClaw (API Key)

Step 1: Generate an MCP API Key

Step 2: Configure OpenClaw using mcporter

Install mcporter

Configure BubblaV in OpenClaw

Manual Configuration

Step 3: Test the Connection

Option 4: OpenClaw (Automatic Setup)

Setup Everything Automatically

Rate Limits

Security

Authentication Methods

API Key & Token Management

Scopes

Audit Logging

Troubleshooting

Connection Issues

Tool Errors

Knowledge Base Not Available

Example Use Cases

Customer Support Agent

Reporting Bot

Knowledge Search API

Knowledge Gap Auto-Filler

Custom Tool Manager

Lead Pipeline Agent

Support

API Reference

Endpoints

Error Codes