> ## Documentation Index
> Fetch the complete documentation index at: https://bavlio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (Model Context Protocol)

> Two MCP surfaces — a docs MCP server live today (queries the documentation), and a planned API-action MCP server (drives the live API).

Bavlio exposes two distinct MCP surfaces:

<CardGroup cols={2}>
  <Card title="Docs MCP — live today" icon="book-open" href="#docs-mcp-live">
    Lets agents query the Bavlio documentation by tool calls (search, fetch page). Auto-generated from this site.
  </Card>

  <Card title="API-action MCP — roadmap" icon="bolt" href="#api-action-mcp-roadmap">
    Lets agents take actions against the live Bavlio API (create campaigns, send email, search leads). Planned.
  </Card>
</CardGroup>

## Docs MCP — live <a id="docs-mcp-live" />

Auto-published by the docs platform at:

```text theme={null}
https://bavlio.mintlify.app/mcp
```

Use cases: any agent that needs to *consult* Bavlio's documentation (e.g., a Cursor session writing integration code, a Claude Desktop session debugging a 401, an autonomous agent learning the API surface). The MCP server exposes search and page-fetch tools that read this site directly.

### Quick install (Cursor)

Add to your Cursor MCP config:

```json theme={null}
{
  "mcpServers": {
    "bavlio-docs": {
      "url": "https://bavlio.mintlify.app/mcp"
    }
  }
}
```

### Quick install (Claude Desktop)

Open Claude Desktop's MCP config and add:

```json theme={null}
{
  "mcpServers": {
    "bavlio-docs": {
      "transport": { "type": "http", "url": "https://bavlio.mintlify.app/mcp" }
    }
  }
}
```

### What this covers vs. doesn't

**Covers:** every page on this site — Quickstart, Authentication, Errors, Pagination, Rate Limits, Webhooks, the full API Reference (190 endpoints with request/response schemas), and the OpenAPI spec.

**Doesn't cover:** taking actions against the API. Agents using only the docs MCP can read docs but can't, for example, create a campaign or send an email. For that you need the API-action MCP below — or just call the REST API directly with a `bav_live_` key.

***

## API-action MCP — roadmap <a id="api-action-mcp-roadmap" />

<Warning>
  **Status: not yet available.** The endpoint, package, and tool surface below are previews — the API-action MCP is not yet shipped. Do not paste the install command yet; it will fail.
</Warning>

A separate MCP server that wraps the Bavlio REST API as agent-callable tools. Lets an agent create campaigns, send emails, search leads, etc. without writing HTTP plumbing.

### Planned install path

```text theme={null}
npx add-mcp https://mcp.bavlio.com/mcp
```

Transport: Streamable HTTP. Auth: Bearer token using your existing `bav_live_` API key.

### Planned tool surface

Initial tool set targets the most common agent workflows: campaign lifecycle, lead management, send + reply, plus the two stateless email primitives.

| Tool                    | Read-only | Destructive | Idempotent | Description                                                    |
| ----------------------- | --------- | ----------- | ---------- | -------------------------------------------------------------- |
| `list_campaigns`        | yes       | no          | yes        | List campaigns with optional status filter.                    |
| `create_campaign`       | no        | no          | no         | Create a new campaign in DRAFT state.                          |
| `launch_campaign`       | no        | no          | yes        | Launch a DRAFT campaign after preflight checks pass.           |
| `pause_campaign`        | no        | no          | yes        | Pause an active campaign.                                      |
| `search_leads`          | yes       | no          | yes        | Search leads in a campaign by name, company, or status.        |
| `add_leads_to_campaign` | no        | no          | no         | Append leads to a campaign from a CSV/JSON payload.            |
| `send_email`            | no        | no          | no         | Send a transactional email via the BaviMail proxy.             |
| `list_replies`          | yes       | no          | yes        | List recent inbound replies (untrusted-content envelope).      |
| `get_campaign_stats`    | yes       | no          | yes        | Aggregate campaign metrics (sent, delivered, opened, replied). |
| `verify_email`          | yes       | no          | yes        | SMTP-probe an email address; returns valid/invalid/risky.      |

### Design notes

* **Untrusted-content envelope.** Tools that surface third-party content (inbound replies) wrap responses in `{ __untrusted_third_party_content: true, content: ... }`. The fence is a machine-readable signal that a trust boundary was crossed. Same pattern as `@bavimail/mcp-server`.
* **No client-side caching of API keys.** The server reads the API key on every call; key rotation takes effect without restart.
* **Tool annotations.** Every tool ships with `readOnlyHint`, `destructiveHint`, and `idempotentHint` per the MCP spec.

### Until then

Use the REST API directly. The [Quickstart](/quickstart) covers everything an agent needs. The API-action MCP is a convenience layer on top — the underlying capability is already available today via REST.