MCP overview

How Buzzabout exposes itself as an MCP server, what tools are available, and how to authenticate.

The Buzzabout MCP server exposes the same primitives as the REST API as a set of tools that any Model Context Protocol client can call — Claude Desktop, Claude on the web, custom agents, or your own integration.

Transport

https://api.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://api.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. Configure your client with the trailing slash up front.

Connecting

Wire the URL above into your MCP client. The streamable-HTTP transport handles tool discovery, tool calls, and OAuth in a single endpoint — no separate SSE channel.

Authentication

Two paths:

x-api-key — same key as the REST API. Header is checked first on every request. Best for headless agents.
OAuth 2.1 — interactive clients (Claude Desktop, Claude web) exchange an authorisation code for a JWT. The server issues the JWT on the user's behalf.

The Authorization: Bearer <jwt> and x-api-key paths share the same User extraction — every tool sees the same authenticated user regardless of how the request authenticated.

One exception: buzzabout__ask

buzzabout__ask impersonates a user against the AI assistant chat backend, so it requires the OAuth/JWT path. API-key callers get a structured forbidden error. All ten other tools work fine with either auth method.

What's exposed

Eleven tools, namespaced buzzabout__* to avoid collisions in hosts that connect multiple MCP servers.

Tool reference

All 11 tools at a glance — name, purpose, required parameters.

buzzabout__ask

The chat tool — hand a prompt to the AI assistant, get markdown + structured references back.

Connect Claude

Install in Claude Desktop / Claude web with OAuth.

Headless agent install

Wire the MCP server into a custom agent using x-api-key.

Tool selection model

Tools split cleanly into three groups:

Thin REST-mirror tools — buzzabout__list_datasets, buzzabout__get_dataset, buzzabout__create_dataset, buzzabout__create_dataset_run, buzzabout__get_dataset_run, buzzabout__create_audience_dataset, buzzabout__create_audience_dataset_run, buzzabout__get_audience_dataset_run, buzzabout__list_mentions, buzzabout__list_audience_profiles.
Chat tool — buzzabout__ask delegates to the AI assistant for conversational analysis.
(No PATCH / DELETE tools — admin actions stay in the web app. No list_audience_datasets / list_*_runs — buzzabout__ask covers those use cases conversationally.)

Async runs

Tools that kick off async work (buzzabout__create_dataset_run, buzzabout__create_audience_dataset_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 buzzabout__get_dataset_run / buzzabout__get_audience_dataset_run until status.type is completed or failed.

When to use MCP vs the API

Use MCP	Use REST
Interactive — a person talking to Claude.	Batch — scheduled job, cron-driven sync.
The host LLM does the orchestration.	You're writing the orchestration.
You want `buzzabout__ask` 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 Claude to summarise via MCP) work naturally.

Tools reference — the eleven tools, table form.
buzzabout__ask deep-dive — input shape, response shape, references.
Connect Claude — install in Claude Desktop / web.
Headless / API key — wire MCP into your own agent.
Recommended dev tools — Agentation and other tools that pair well with Buzzabout MCP.