API MCP Server

The Cavai API MCP server allows AI assistants to manage the Cavai platform — creating campaigns, editing creatives, generating reports, uploading assets, and more. It exposes 61 tools across 13 domains via the Model Context Protocol.

For the read-only documentation server, see Docs MCP Server.

Endpoint

https://mcp.cavai.com/mcp

The endpoint uses the MCP Streamable HTTP transport.

Authentication

No API keys or credentials are needed in your client configuration. Authentication happens in the browser:

1. Connect — point your MCP client at the endpoint URL
2. First tool call — the server returns a login URL
3. Browser login — open the URL and sign in with your Cavai account
4. Authenticated — subsequent tool calls work normally

If your backend session expires, the server returns a fresh login URL automatically. Each client connection gets its own isolated session.

Rate Limiting

The server enforces a per-session rate limit on tool calls. The default limit is 30 tool calls per minute. The login tool is exempt — authentication always works regardless of rate limit status.

When the limit is exceeded, the server returns an error and the AI assistant automatically adjusts by reducing the number of calls. If you notice the assistant pausing or mentioning rate limits, this is expected behavior.

TIP

To stay within the limit, ask the assistant to use batch-oriented approaches — for example, listing entities in bulk rather than fetching them one by one.

Client Configuration

Claude Desktop

Go to Settings > Connectors > Add MCP Server and enter the endpoint URL:

https://mcp.cavai.com/mcp

No additional configuration is needed.

Claude Code

claude mcp add --transport http cavai https://mcp.cavai.com/mcp

Or add to your settings (.claude/settings.json):

{
  "mcpServers": {
    "cavai": {
      "type": "http",
      "url": "https://mcp.cavai.com/mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "cavai": {
      "type": "streamable-http",
      "url": "https://mcp.cavai.com/mcp"
    }
  }
}

Available Tools

61 tools organized by domain:

Domain	Count	Operations
Auth	1	login
Enterprises	2	list, get
Workspaces	4	list, get, list-for-selection, list-templates
Brands	7	list, get, list-for-selection, create, update, update-logo, delete-logo
Campaigns	8	list, get, list-data-tree, clone, create, update, update-logo, delete-logo
Creative Groups	7	list, get, list-creatives, fetch-attributes, clone, create, update
Creatives	20	get, get-preview, get-build-status, get-creative-tag, clone, create, update, patch-creative-operator, patch-creative-block, build, store-asset, get-cloudflare-upload-url, list-versions, restore-version, update-version, bulk-create-mass-format, add-children-to-mass-format, update-mass-format, dissociate-all-children, dissociate-single-child
Users	2	list, get
Me	1	get (current user info)
Search	1	global search
Aggregation	5	counts, buckets, flow, raw-flow, daily-flow
Reports	1	make-report (CSV/Excel)
Uploads	2	start-upload-session, get-session-uploads

Tools follow the Cavai entity hierarchy: Enterprise > Workspace > Brand > Campaign > Creative Group > Creative. Most tools require a workspace_id as context.

Reports

The cavai_make_report tool generates CSV or Excel reports from analytics data. The server creates the file and returns a download link. Reports auto-expire after 24 hours.

Available metrics

Both cavai_make_report and cavai_get_buckets accept a metrics parameter. Use "base" to include all metrics, or request specific ones:

Metric	Description
impressions	Total creative impressions
interacted	Impressions that led to interaction
started	Users who started the conversation
continued	Users who continued past the first action
creative_actions	Total actions taken
link_clicks	Link clicks
header_clicks	Header clicks
background_clicks	Background clicks
reached_end	Users who reached the end
plays	Video plays
watched_25 / watched_50 / watched_75 / watched_100	Video quartile completion
viewable_impressions	Impressions that met the IAB viewability threshold
seconds_in_view	Total seconds the creative was in the viewable area

Calculated metrics

These can be derived from the raw metrics above:

Metric	Formula	Description
Time spent	seconds_in_view / viewable_impressions	Average seconds per viewable impression
Viewability	viewable_impressions / impressions	Percentage of impressions that were viewable

Asset Uploads

AI assistants can't send files directly, so asset uploads use a two-step browser flow:

1. The assistant calls cavai_start_upload_session — this returns a URL to a browser upload page
2. You open the URL, drag and drop your files (images, videos, etc.), and confirm in chat
3. The assistant calls cavai_get_session_uploads to retrieve the CDN URLs of your uploaded files
4. The assistant uses those URLs in creative blobs (e.g., background images, logos)

Creative Responses

The cavai_get_creative tool accepts an optional fields parameter that controls how much data is returned:

Value	Description
full	Returns everything including the creative blob (default)
metadata	Strips creative_blob from the response — returns ID, name, stub file, build status, dimensions, timestamps, and all other fields

Use fields=metadata when you need to check build status, confirm a creative exists, or read basic properties without loading the full blob into context. The blob can be 50 KB or more, so this option significantly reduces context usage when the blob content is not needed.

Granular Creative Editing

Creative blobs can be large (50 KB or more). Two tools allow targeted edits without sending the full blob through the AI context window:

Tool	Target	Edits
cavai_patch_creative_operator	Flow operators (logicSettings.operators)	Text content, goal tracking, link URLs, and other operator properties
cavai_patch_creative_block	Visual blocks (creativeSettings.creativeBlocks)	Background color, font, dimensions, and other block properties

Both tools accept a properties object with dot-path keys mapped to new values. The creative is fetched, patched, and saved automatically — no need to read or write the full blob.

Example — change a text operator:

{
  "id": "12345",
  "operator_key": "statement_0",
  "properties": {
    "body.inputText.value": "Welcome back! Click to learn more."
  }
}

Example — change a block's background color:

{
  "id": "12345",
  "block_key": "baseProperties",
  "properties": {
    "backgroundSettings.color": "#FF6B35"
  }
}

Finding available keys

Call cavai_get_creative first to inspect the blob structure. Use fields=metadata to skip the blob if you only need to confirm the creative exists, then call again without fields to read the full blob and identify operator and block keys.

Example Workflows

Browse and explore

"Show me all campaigns in the Norway workspace"

The assistant calls cavai_list_workspaces to find the workspace, then cavai_list_campaigns to list its campaigns.

Create a campaign structure

"Create a new brand called 'Acme Corp' in workspace 227, then create a campaign under it called 'Summer Sale 2026'"

The assistant calls cavai_create_brand and then cavai_create_campaign, chaining the IDs.

Clone and modify

"Clone the 'Holiday Campaign' and rename it to 'Spring Campaign'"

The assistant finds the campaign, calls cavai_clone_campaign, then cavai_update_campaign to rename it.

Generate a report

"Generate an Excel report for the 'Summer Sale 2026' campaign"

The assistant finds the campaign, calls cavai_make_report with its ID and format. You get a download link.

Get a tag for deployment

"Get the ad tag for creative 12345 for The Trade Desk"

The assistant calls cavai_get_creative_tag with the creative ID and DSP name. It returns the ready-to-use <script> snippet with TTD-specific click macro, domain, and cache-buster placeholders. The creative must be built before a tag can be generated — if not, the tool returns an error and suggests running cavai_build_creative first.

Upload assets and create a creative

"I have some brand assets to use in a new creative"

The assistant starts an upload session, you upload files in the browser, and the assistant creates a creative using the CDN URLs from your uploaded assets.

Using Both Servers Together

The Docs MCP and API MCP servers complement each other:

• Docs MCP — provides knowledge about the platform (creative data format, analytics events, ad formats, configuration options)
• API MCP — performs actions on the platform (create, update, build, report)

When both are connected, an AI assistant can look up how creative JSON is structured (via Docs MCP), then create a creative with the correct format (via API MCP). This is particularly useful for building creatives programmatically — the assistant searches the creative data documentation for the right block types, operators, and styling, then assembles and saves the creative through the API.

No special configuration is needed to use both — just add both servers to your MCP client.

Source Code

Repository: github.com/Cavai/cavai-mcp (Cavai org, private)