---
title: "MCP server"
description: "Connect an AI agent to your BackTalk workspace over the Model Context Protocol (MCP). Streamable HTTP transport, bearer API-key auth, and tools to list, read and triage signals — with setup for Claude Code, Claude Desktop and ChatGPT."
source: https://backtalk.sh/docs/mcp
---
# MCP server

BackTalk ships an [MCP](https://modelcontextprotocol.io) server so an AI agent can read and triage your signals directly — "what did developers complain about today?" answered from your live inbox. It uses the **Streamable HTTP** transport and the **same API keys** as the REST API.

Endpoint: `https://backtalk.sh/api/mcp`
Auth: `Authorization: Bearer btk_YOUR_KEY` (create one in **Settings → API keys**).

## Tools

| Tool | Scope | What it does |
| ---- | ----- | ------------ |
| `whoami` | any | Which workspace and scopes the key carries (the MCP twin of REST `GET /me`). |
| `list_signals` | read | Filtered, paginated list of signals (compact rows): status, source, sentiment, priority, category, intent, free-text `search`, `sort` newest/oldest. |
| `get_signal` | read | Full detail for one signal. |
| `list_keywords` | read | The workspace's keywords. |
| `list_watchers` | read | The workspace's watchers. |
| `report` | read | Rollup for `today` / `7d` / `30d`, or a custom `since`/`until` range (volume, sentiment, per-source, trend). |
| `list_ai_topics` | read | The AI share-of-voice topics the workspace tracks. |
| `get_share_of_voice` | read | Standings and trend for one topic: who AI models recommend, you vs competitors. |
| `list_ai_answers` | read | The sampled AI answers behind the numbers, with extracted mentions and citations. |
| `list_syncs` | read | Sync-run history: trigger, derived status, totals and per-source breakdown (companion to `trigger_sync`). |
| `probe_status` | read | Whether a probe is running (with live progress) plus today's manual-probe allowance (companion to `trigger_probe`). |
| `triage_signal` | **write** | Set a signal's state (new/seen/replied/ignored), star it, override its sentiment, or record an ignore reason. |
| `triage_signals` | **write** | The same triage patch applied to a batch of signal ids at once (up to 100). |
| `curate_answer` | **write** | Star a sampled AI answer, or flag it as a wrong extraction. |
| `trigger_sync` | **write** | Fetch new signals on demand (subject to the same daily cap as the in-app "Sync now"). |
| `trigger_probe` | **write** | Run a fresh AI share-of-voice probe; returns a run_id, results land in a minute or two. |

The write tools (`triage_signal`, `triage_signals`, `curate_answer`, `trigger_sync`, `trigger_probe`) are only registered when your key has the `write` scope, so a read-only key never sees them; `whoami` needs no scope. The demo question *"what did developers complain about today?"* is answered by `report` (`period=today`) together with `list_signals` (`sentiment=["negative"]`, `since=<today>`).

> **Prompt-injection note.** Signal content (title, snippet, author, url) is **untrusted third-party text** scraped from the public internet. The tool descriptions say so, and your agent should treat returned content as data to analyse — never as instructions to follow.

## Connect Claude Code

```bash
claude mcp add --transport http backtalk https://backtalk.sh/api/mcp \
  --header "Authorization: Bearer btk_YOUR_KEY"
```

Then ask Claude things like *"Use backtalk: what did developers complain about today?"* The exact `claude mcp add` command (with your key filled in) is shown on the **Settings → API keys** page after you create a key.

## Connect Claude Desktop

Claude Desktop can't take a bearer header directly: its config file only launches **local (stdio) servers**, and the **Add custom connector** screen in Settings expects OAuth, which BackTalk doesn't support yet. Bridge the endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) instead; it needs Node.js installed.

First **quit Claude Desktop fully** (Cmd+Q on macOS). The app rewrites its config file on exit, so edits made while it's running are lost. Then add this to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`, or **Settings → Developer → Edit Config** in the app) and relaunch:

```json
{
  "mcpServers": {
    "backtalk": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://backtalk.sh/api/mcp",
        "--header",
        "Authorization: Bearer btk_YOUR_KEY"
      ]
    }
  }
}
```

On Windows, spaces inside `args` can get mangled before they reach the server; if the connection fails with an auth error, pass `"--header", "Authorization:${AUTH_HEADER}"` in `args` and add `"env": { "AUTH_HEADER": "Bearer btk_YOUR_KEY" }` to the entry.

## Connect ChatGPT

In a ChatGPT client that supports custom MCP connectors (Developer mode / custom connectors), add a connector with:

- **Transport / type:** HTTP (Streamable HTTP)
- **URL:** `https://backtalk.sh/api/mcp`
- **Header:** `Authorization: Bearer btk_YOUR_KEY`

ChatGPT's MCP support leans on the read tools (`list_signals`, `get_signal`, `report`) for search-and-fetch style use.

## Auth, scopes and limits

- **Auth** is the same bearer API key as REST; a bad or missing key gets a `401` with `WWW-Authenticate: Bearer`. OAuth / dynamic client registration is future work.
- **Scopes** work exactly as in the REST API: read tools need `read`, the write tools (`triage_signal`, `triage_signals`, `curate_answer`, `trigger_sync`, `trigger_probe`) need `write`, `whoami` needs only a valid key, and a read-only workspace refuses every write tool.
- **Roles** apply here too: a key whose creator has been demoted to [viewer](/docs/members) can still read, but every write tool refuses until they are promoted back. Removing them from the workspace stops the key entirely.
- **Rate limits** are the same per-key budget (120 requests/minute); over it, the server returns `429`.

See the [REST API guide](/docs/api) for scopes, error codes, and rate-limit details in full.