> ## 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**, 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:**

```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

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):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```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"
}
```

## 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. **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 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:**

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

```yaml theme={null}
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:

```yaml theme={null}
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:

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

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

```yaml theme={null}
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](mailto: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