---
title: "MCP server"
description: "Connect an AI assistant to your CookieBeam account over the Model Context Protocol."
url: "https://cookiebeam.com/docs/api-reference/mcp"
lang: "en"
---

# MCP server

Connect an AI assistant to your CookieBeam account over the Model Context Protocol.

CookieBeam hosts a Model Context Protocol (MCP) server, so an AI assistant that speaks MCP can read your banners, scan results, and consent analytics directly instead of you copying data into a chat. There is nothing to install: the server is hosted, and it authenticates with the same API keys as the rest of the public API.

## Endpoint

```text
POST https://cookiebeam.com/api/mcp
```

The server speaks Streamable HTTP in stateless JSON mode. Every request is self-contained — there are no sessions, so `GET` (the SSE channel) and `DELETE` (session teardown) return HTTP 405. Most MCP clients handle this for you; you only need the URL and a key.

## Connect a client

Point your client at the endpoint and send your API key as a bearer token. In a client that takes JSON configuration, that usually looks like this:

```json
{
  "mcpServers": {
    "cookiebeam": {
      "url": "https://cookiebeam.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cb_live_your_key_here"
      }
    }
  }
}
```

Keys are created as described in [Authentication](https://cookiebeam.com/docs/api-reference/authentication), and the same rules apply here: a key acts as the whole team, and API access requires a plan that includes the API feature. Every tool is read-only, so a **test key works for all of them** — a good way to try the server without touching production data.

Clients must send `Accept: application/json, text/event-stream` on the POST, as the MCP specification requires. A compliant client does this automatically; a hand-rolled request without it receives HTTP 406.

## Account tools

These read your team's data and each requires a scope on the key. If the key is missing one, the tool returns an MCP tool error naming the scope it needed, rather than failing the whole request — so an assistant can tell you what to fix.

| Tool | Scope | Returns |
| ---- | ----- | ------- |
| `list_banners` | `banners:read` | Your banners with domain, status, and framework flags |
| `get_banner` | `banners:read` | One banner in detail |
| `get_embed_code` | `banners:read` | The install snippet and per-environment script URLs |
| `list_scans` | `scanner:read` | Recent scans with status and cookie counts by category |
| `list_discovery_inventory` | `scanner:read` | Paginated cookies, scripts, and connections in one normalized contract, with source, review status, timestamps, totals, and type-specific details |
| `get_scan_results` | `scanner:read` | **Deprecated:** one scan's legacy summary; migrate to `list_discovery_inventory` before removal on December 1, 2026 |
| `get_consent_analytics` | `analytics:read` | Consent totals and accept/reject rates for a date range |

## Classification tools

These four analyse data you supply and touch no account data, so they need a valid key but no particular scope:

| Tool | Returns |
| ---- | ------- |
| `classify_cookie` | A cookie's category and vendor from its name |
| `classify_script` | A script URL's category and vendor |
| `classify_connection` | An outbound connection's category from its destination |
| `get_compliance_status` | An assessment of scripts, cookies, and connections you pass in |

`get_compliance_status` judges only the inventory you give it and performs no network requests. A full CookieBeam scan remains the authoritative audit of a site.

## Errors

Authentication and rate limiting behave exactly as they do elsewhere in the public API — see [Errors and limits](https://cookiebeam.com/docs/api-reference/errors-and-limits). A missing or invalid key returns HTTP 401 before any tool runs, and rate-limit headers are returned on every response.

Failures inside a tool (a missing scope, an unknown banner id) come back as MCP tool errors rather than HTTP errors, which is what lets an assistant report the problem and carry on rather than dropping the connection.