buzzabout docsMCP overview
How buzzabout exposes itself as an MCP server, what tools are available, and how to authenticate.
The buzzabout MCP server exposes the full public REST surface as a set of tools any Model Context Protocol client can call — Claude Desktop, Claude on the web, Cursor, ChatGPT, your own SDK-built agent.
Transport
https://mcp.buzzabout.ai/mcp/Streamable HTTP transport (the modern MCP transport — no separate SSE endpoint). One URL handles tool listing, tool calls, and OAuth discovery.
Trailing slash is required
Use https://mcp.buzzabout.ai/mcp/ (with trailing slash). The
unslashed /mcp returns a 307 redirect that strips the request
body in many MCP clients, which surfaces as silent connection
failures or empty tool lists.
Connecting
Wire the URL above into your MCP client. The streamable-HTTP transport handles tool discovery, tool calls, and OAuth on a single endpoint — no separate SSE channel.
See Use in your agent for per-host wiring snippets (Claude Desktop, Claude.ai, Cursor, ChatGPT, custom SDKs).
Authentication
Two paths:
x-api-key— same key as the REST API. Best for headless agents.- OAuth → JWT — interactive clients exchange an authorisation code for a JWT on first connection.
Both resolve to the same authenticated User. Full details on
Authentication.
What's exposed
32 tools across 9 groups. Each tool's description opens with a
[<Group>] prefix for in-list scannability.
| Group | Count | Examples |
|---|---|---|
datasets | 8 | create / list / get / update / delete dataset + dataset_run trio |
mentions | 1 | buzzabout__list_mentions |
audience_datasets | 8 | same CRUD + run trio as datasets |
audience_profiles | 1 | buzzabout__list_audience_profiles |
tracking_agents | 8 | create / list / get / pause / resume / delete / trigger_run / list_messages |
patterns | 4 | create_pattern_detection, get_pattern_detection_run, get_pattern, get_pattern_item |
custom_parameters | 9 | full CRUD + preview + trigger_run / list_runs / get_run |
chat | 3 | ask, get_chat, list_chat_messages |
account | 2 | get_me, list_usage_history |
Tools reference
Every tool — name, group, required parameters, returned shape.
Use in your agent
Per-host wiring + a first prompt to test the loop.
Authentication
x-api-key for headless agents, OAuth for interactive hosts.
REST-only (no MCP tool): GET /v1/credit_prices (static price
table) and PATCH /v1/tracking_agents/{id} (uncommon admin op).
Group filtering
Append ?groups=... to the connection URL to limit the handshake's
tools/list to a subset:
https://mcp.buzzabout.ai/mcp/?groups=datasets,mentions,chatDefault (no param) = all groups. Most MCP hosts also expose per-tool toggles in their settings UI for finer-grained filtering on a per-conversation basis.
Async runs
Tools that kick off async work
(buzzabout__create_dataset_run,
buzzabout__create_audience_dataset_run,
buzzabout__create_pattern_detection,
buzzabout__trigger_custom_parameter_run,
buzzabout__trigger_tracking_agent_run) return immediately:
{
"run_id": "dr_01H...",
"dataset_id": "ds_01H...",
"status": "pending",
"next_step": "Call buzzabout__get_dataset_run with this run_id to poll completion.",
"created_at": "2026-05-01T12:00:30Z"
}The host LLM polls the corresponding get_*_run tool until
status.type is completed or failed.
When to use MCP vs REST
| Use MCP | Use REST |
|---|---|
| Interactive — a person talking to an LLM client. | Batch — scheduled job, cron-driven sync. |
| The host LLM does the orchestration. | You're writing the orchestration. |
| You want the assistant to drive the workflow. | You only need primitive CRUD. |
Both surfaces are backed by the same primitives, so hybrid setups (e.g. schedule the run via REST, ask an MCP-capable assistant to summarise) work naturally.
See also
- Agentation — third-party MCP devtool that pairs well with buzzabout for local agent development and inspection.
Next steps
- Tools reference — the full 32-tool surface.
- Use in your agent — per-host wiring + first prompt.
- Authentication — pick
x-api-keyor OAuth/JWT.