Connect an AI assistant
Give Claude, ChatGPT or Cursor access to a Listener workspace through the MCP server.
3 min read
Listener runs a Model Context Protocol server, so AI assistants can read a workspace and make guarded changes in plain language: “Which shows grew fastest last quarter?”, “Build clusters for this week’s episodes”, “Create a campaign from this insertion order”.
The server exposes more than 80 tools over the same metric code as the API and the apps, so an assistant quotes the same numbers your dashboard shows, with the window, coverage and freshness behind them.
| Server URL | https://mcp.listener.com/mcp |
| Transport | Streamable HTTP |
| Authentication | Sign in with Listener (OAuth), or an API key |
https://api.listener.com/mcp serves the same server.
Sign in with Listener (recommended)#
Clients that support MCP authorization discover Listener’s OAuth server automatically: add the server URL without a key, and the client opens a Listener sign-in and consent screen. You choose the workspace and whether the assistant may only read (“Full read access”) or also write (“Full write access”). Revoke it any time under Settings → Developers → Authorized apps.
Claude (claude.ai and Claude Desktop)#
- Open Settings → Connectors → Add custom connector.
- Name it Listener and paste
https://mcp.listener.com/mcp. - Choose Connect and sign in with your Listener account.
ChatGPT#
- Turn on Developer mode under Settings → Connectors → Advanced.
- Create a connector with the URL
https://mcp.listener.com/mcpand OAuth authentication. - Sign in with Listener when prompted.
Claude Code#
claude mcp add --transport http listener https://mcp.listener.com/mcpThen run /mcp inside Claude Code and choose Authenticate for listener.
Connect with an API key#
For clients without OAuth support, or for automation, use an API key from Settings → Developers. Pick the Read preset unless you want the assistant to make changes.
claude mcp add --transport http listener https://mcp.listener.com/mcp \
--header "Authorization: Bearer lsk_…"The Cursor entry goes in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
The URL form puts the key in the connector URL, for clients that can neither do OAuth nor send headers. It is accepted on the MCP endpoint only, and the key is stripped from the URL before anything is logged. Prefer OAuth or the header form wherever you can, and never share a URL that contains a key.
What the assistant can do#
| Area | Examples |
|---|---|
| Workspace | List shows, plan, team, integrations and their freshness. |
| Analytics | Reach summaries, timelines, rankings, comparisons, platform splits, dashboard KPIs. |
| Episodes and clusters | Search episodes and transcripts, build clusters with AI, add posts, review suggestions. |
| Campaigns | Create and update campaigns and slots, link clusters, check delivered CPM and air checks. |
| Reports and sponsors | Publish shared reports, match sponsors, find bundle opportunities. |
Write tools follow the same rules as the API: they preview with dry_run, and deletes, publishing and metered refreshes need explicit confirmation. A Read key or a read-only grant cannot change anything.
Scopes#
An assistant signed in with OAuth needs workspace:read, plus workspace:write for write tools. With an API key, the key’s preset decides.
Troubleshooting#
- The client never shows a sign-in screen. It may not support MCP authorization yet. Use the header or URL form with an API key.
- “Unauthorized” after it worked before. The key was rotated or revoked, or the grant was removed under Authorized apps. Reconnect.
- Numbers look low. Ask the assistant for the freshness of each platform. See Data freshness.