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, and OpenClaw. This allows your AI agents to search your knowledge base and access analytics reports in real-time.

What Can You Do?

Search Knowledge Base: Let your AI agents search your indexed website content
Access Analytics: Retrieve conversation and performance reports programmatically
Scrape Web Pages: Convert any public URL into markdown with bubblav_scrape_url
Build Automations: Create custom workflows that leverage your BubblaV data
Real-time Integration: Use Server-Sent Events (SSE) for instant data access

Available Tools

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

Retrieve conversation or performance analytics reports. Parameters:

report_type (string, required): Type of report - "conversations" or "performance"
date_range (object, optional): Date range for the report
- start (string): Start date in ISO format (e.g., “2026-03-01”)
- end (string): End date in ISO format (e.g., “2026-03-18”)

Returns (conversations):

{
  "reportType": "conversations",
  "period": { "start": "2026-03-01", "end": "2026-03-18" },
  "metrics": {
    "totalConversations": 1234,
    "resolvedByBot": 856,
    "handedToHuman": 378,
    "resolutionRate": 0.69,
    "avgResponseTimeSeconds": 12.5,
    "topQueries": [
      { "query": "shipping policy", "count": 45 },
      { "query": "return policy", "count": 32 }
    ]
  }
}

Returns (performance):

{
  "reportType": "performance",
  "period": { "start": "2026-03-01", "end": "2026-03-18" },
  "metrics": {
    "botVsHumanSplit": { "bot": 0.7, "human": 0.3 },
    "csatAverage": 4.2,
    "avgConversationLengthMinutes": 3.5,
    "peakHours": ["10:00-11:00", "14:00-15:00"]
  }
}

Example:

{
  "report_type": "conversations",
  "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"
}

Setup Guide

BubblaV MCP Server supports these connection methods:

ChatGPT - OAuth 2.0, no API key needed
Claude / Claude Desktop - OAuth 2.0, no API key needed
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

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 analytics reports
bubblav_add_knowledge - Add new knowledge entries to your knowledge base

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
- 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
Starter	1,000
Pro	5,000
Turbo	15,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 Integrations → MCP Settings → Audit Logs

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
instructions: |
  You are a customer support agent with access to our knowledge base.
  Search for relevant information and provide helpful responses.
  You can also access conversation analytics to identify trends.

Reporting Bot

Build a bot that generates monthly performance reports:

name: reporting-bot
tools:
  - bubblav_read_report
schedule: "0 9 1 * *"  # First day of every month at 9 AM
instructions: |
  Generate a performance report for the past month
  and summarize key metrics.

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 Update Agent

Build an agent that can identify content gaps and fill them in automatically:

name: knowledge-update-agent
tools:
  - bubblav_search_knowledge
  - bubblav_read_report
  - bubblav_add_knowledge
instructions: |
  Monitor for unanswered questions and low-confidence responses.
  When you find a gap, search for the answer internally
  and add it to the knowledge base using bubblav_add_knowledge.

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
401	Authentication failed (invalid or missing API key/token)
403	Insufficient scopes
429	Rate limit exceeded
500	Internal server error

Changelog

v1.3.0 (2026-03-24)

Added bubblav_add_knowledge tool for adding text knowledge entries to the knowledge base
Content is automatically chunked and queued for embedding
Plan page limits are enforced for knowledge additions
Added “Option 3: OpenClaw (Automatic Setup)” to guide OpenClaw setup via natural language prompt

v1.2.0 (2026-03-23)

Claude connection now requires only the server URL — no API key or config file
Added /.well-known/oauth-authorization-server OAuth discovery endpoint
Authorization flow shows website-selection consent page instead of requiring API key as client_id
OAuth tokens no longer tied to a specific API key
OpenClaw URL corrected to /api/mcp (not /api/mcp/sse)

v1.1.0 (2026-03-23)

Added OAuth 2.0 support for Claude Desktop
PKCE (Proof Key for Code Exchange) for enhanced security
OAuth token refresh support
Dual authentication: OAuth tokens and API keys

v1.0.0 (2026-03-18)

Initial release
Knowledge base search tool
Conversations and performance report tools
SSE and HTTP endpoints
Rate limiting by plan
Audit logging

Documentation Index

​BubblaV MCP Server

​What Can You Do?

​Available Tools

​bubblav_search_knowledge

​bubblav_read_report

​bubblav_add_knowledge

​bubblav_scrape_url

​Setup Guide

​Option 1: ChatGPT (OAuth 2.0)

​Option 2: Claude (OAuth 2.0)

​Step 1: Add the BubblaV connector

​Step 2: Authorize

​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 Update Agent

​Support

​API Reference

​Endpoints

​Error Codes

​Changelog

​v1.3.0 (2026-03-24)

​v1.2.0 (2026-03-23)

​v1.1.0 (2026-03-23)

​v1.0.0 (2026-03-18)

BubblaV MCP Server

What Can You Do?

Available Tools

bubblav_search_knowledge

bubblav_read_report

bubblav_add_knowledge

bubblav_scrape_url

Setup Guide

Option 1: ChatGPT (OAuth 2.0)

Option 2: Claude (OAuth 2.0)

Step 1: Add the BubblaV connector

Step 2: Authorize

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 Update Agent

Support

API Reference

Endpoints

Error Codes

Changelog

v1.3.0 (2026-03-24)

v1.2.0 (2026-03-23)

v1.1.0 (2026-03-23)

v1.0.0 (2026-03-18)