How-to guide

Connect an agent

Ask questions about a project from Claude, ChatGPT, or Codex over MCP.

Connect an AI agent to an analysed project and ask questions about it in the agent's own window — Claude Code, Claude Desktop, the ChatGPT desktop app, Codex, or any agent that speaks MCP (the Model Context Protocol). The agent reads the quotes in your report, your sections and themes, your signals, and your codebook, and cites quote IDs you can look up.

Available in the macOS app and on the command line.

What the agent can see

  • The quotes in your report — verbatim, and curated: quotes you have hidden are excluded, and where you have edited a quote the agent reads your edited version.
  • Your report structure — sections, themes, and the signals from the Analysis lens.
  • Your codebook — framework codes and your own codes, with their definitions and boundaries.
  • Speaker codes with names alongside, unless you anonymise — the same Anonymise word as the export surfaces. In the Mac app it's one switch at the top of Settings → MCP Agents, applying to everything agents read, off by default; switch it on and agents see codes (p1, m1) only. The command line doesn't yet expose this switch.

Quote text is sent exactly as it appears in your report. If a participant says their own name — or anyone else's — inside a quote, that name goes to the agent. Redact personal information before connecting an agent if that matters for your study.

The connection is read-only: nothing an agent does can change your report, your quotes, or your codebook.

Install and start

Mac app

Two acts, and they are different sizes:

  1. Turn on agent access for the project. Right-click it in the sidebar and choose Turn On Agent Access — or use the project list in Settings → MCP Agents. This is per project: a project you never turn on can never be reached, no matter what agents you have installed. An antenna glyph on the project's row shows it is shared — solid while the project is open (reachable now), pale while it isn't.

  2. Connect your agent, once. Open Settings → MCP Agents (or Bristlenose → Connect an Agent…). For Claude Desktop, click Install Extension… and confirm in Claude Desktop — no address, no token, no config file, and nothing to redo when Bristlenose restarts. For other agents, pick the tab for yours and copy what it shows.

Agents read whichever project is selected in Bristlenose — switch project and the agent's answers follow, among the projects you have turned on.

Command line

Connecting agents needs one extra package:

pip install 'bristlenose[mcp]'

Then serve the project you want to connect:

bristlenose serve interviews

Bristlenose prints the two things every agent needs — the MCP address and an authorization header:

MCP:    http://127.0.0.1:8150/mcp/

  Authorization: Bearer <your token>

Leave the server running while you use the agent.

Mac app

The extension finds the running project by itself, so a Bristlenose restart needs nothing redone. Only configs copied from the other tabs carry an address, and that address changes when Bristlenose restarts — re-copy after a relaunch.

Command line

The token changes each time you restart the server. If your agent reports 401 Unauthorized after a restart, reconnect it with the new token.

Connect your agent

Each agent writes those two values down slightly differently. Pick yours.

Claude Code

claude mcp add --transport http bristlenose http://127.0.0.1:8150/mcp/ \
  --header "Authorization: Bearer <your token>"

Type /mcp in Claude Code to confirm it connected.

Avoid --scope project. It writes your token into a .mcp.json file inside the project folder, which is easy to commit to a repository by accident.

Claude Desktop

Mac app

Settings → MCP Agents → Install Extension… — Claude Desktop opens and asks you to confirm. Bristlenose then appears in Claude Desktop under Settings → Developer, alongside extensions like Figma. That's the whole setup; there is no config to edit and nothing to re-copy after a restart.

Expect one more prompt, a little later than you might think: the first time you ask a question, macOS asks once whether Claude may access data from other apps. Click Allow — that permission is how the extension finds Bristlenose. It arrives on the first question rather than at install, so it can turn up after setup already looks finished.

Command line

Quit Claude Desktop first — it writes its own state into the config file, so edits made while it runs can be lost. Then add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Settings → Developer → Edit Config opens it) as a new top-level key:

"mcpServers": {
  "bristlenose": {
    "url": "http://127.0.0.1:8150/mcp/",
    "headers": { "Authorization": "Bearer <your token>" }
  }
}

If the file already has an mcpServers key, merge the "bristlenose" entry into it instead. Relaunch Claude Desktop — Bristlenose appears under Settings → Developer.

ChatGPT and Codex

The ChatGPT desktop app, the Codex CLI, and the Codex extension for VS Code share one configuration file, ~/.codex/config.toml. A single entry covers all three:

[mcp_servers.bristlenose]
url = "http://127.0.0.1:8150/mcp/"
http_headers = { "Authorization" = "Bearer <your token>" }

In the ChatGPT app you can also use Settings → MCP servers → Add server, choosing Streamable HTTP. Restart the app after saving.

Any other agent

Give it the MCP address and the authorization header. Bristlenose works with any agent that supports MCP over streamable HTTP.

Agents that run in a web browser — claude.ai or chatgpt.com — cannot reach a server on your own machine. Use a desktop or command-line agent.

Try asking

  • Which codes are doing no work in this study?
  • Draft a top-line from the starred quotes only.
  • Where do participants disagree?
  • Which sections carry the strongest signals, and who is driving them?

Good to know

  • One project at a time. In the Mac app, agents read whichever project is selected, among the projects you have turned on — never one you haven't. On the command line, the agent sees the project you served, and only that one.
  • Your subscription pays for it. Questions run in the agent's own window on your own plan, not through the API key Bristlenose uses for analysis.
  • What you ask becomes part of the agent's history. The quotes an agent reads are held by that agent's provider under their terms. Deleting the project later does not delete that history.
  • Quote text is data, not instructions. Bristlenose tells every agent this on connection. If you work with transcripts from a source you do not control, treat what an agent reports back with the same care you would give the transcript.
Previous Send quotes to Miro