​

BubblaV MCP Server

​

What Can You Do?

• Search Knowledge Base: Let your AI agents search your indexed website content
• Access Analytics: Retrieve conversation and performance reports programmatically
• 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

• query (string, required): Your search query
• limit (number, optional): Maximum results to return (default: 5, max: 20)

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

{
  "query": "shipping policy",
  "limit": 10
}

​

bubblav_read_report

• 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”)

{
  "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 }
    ]
  }
}

{
  "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"]
  }
}

{
  "report_type": "conversations",
  "date_range": {
    "start": "2026-03-01",
    "end": "2026-03-18"
  }
}

​

Setup Guide

​

Step 1: Generate an MCP API Key

1. Log in to your BubblaV dashboard at https://www.bubblav.com
2. Navigate to Integrations → API Keys
3. Click Generate New Key
4. Enter a friendly name (e.g., “OpenClaw Integration”)
5. Select the MCP scopes:
   • mcp:read - Read access to your data
   • mcp:tools:execute - Execute MCP tools
6. Click Generate
7. Important: Copy the API key immediately. It will only be shown once!

bubblav_mcp_a1b2c3d4e5f6g7h8i9j0k1l2

​

Step 2: Configure OpenClaw

1. Install the BubblaV skill in your OpenClaw instance
2. Configure the connection:

name: bubblav
connection:
  url: https://www.bubblav.com/api/mcp/sse
  headers:
    X-API-Key: bubblav_mcp_a1b2c3d4e5f6g7h8i9j0k1l2

3. Save and restart your OpenClaw instance

​

Step 3: Test the Connection

• bubblav_search_knowledge - Search your knowledge base
• bubblav_read_report - Access analytics reports

​

Rate Limits

• Rolling 7-day window (resets every week 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

​

API Key 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

• mcp:read - Read-only access to your website data
• mcp:tools:execute - Execute MCP tools

​

Audit Logging

• Tool name and arguments
• Success/failure status
• API key used
• Timestamp

​

Troubleshooting

​

Connection Issues

• 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

• Check your usage in the dashboard
• Wait for the weekly window to reset (check Retry-After header)
• Consider upgrading your plan for higher limits

​

Tool Errors

• 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

• 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

• 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

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

name: reporting-bot
tools:
  - bubblav_read_report
schedule: "0 9 * * 1"  # Every Monday at 9 AM
instructions: |
  Generate a performance report for the past week
  and summarize key metrics.

​

Knowledge Search API

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();

​

Support

• Email: support@bubblav.com
• Documentation: https://www.bubblav.com/docs
• Community: https://discord.gg/bubblav

​

API Reference

​

Endpoints

GET https://www.bubblav.com/api/mcp/sse
Headers:
  X-API-Key: bubblav_mcp_...

GET https://www.bubblav.com/api/mcp/tools
Headers:
  X-API-Key: bubblav_mcp_...

POST https://www.bubblav.com/api/mcp/call
Headers:
  X-API-Key: bubblav_mcp_...
  Content-Type: application/json
Body:
{
  "toolId": "bubblav_search_knowledge",
  "arguments": {
    "query": "your search query",
    "limit": 10
  }
}

​

Error Codes

​

Changelog

​

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