Agent Integration (MCP Bridge)

This guide is for developers who want to use TraceGist sessions directly from a coding agent (Claude Code, OpenAI Codex, Cursor, Claude Desktop, and any other MCP client).

How it works

The TraceGist extension exports session packages as ZIP files to your Downloads folder, or to a folder you choose. The MCP bridge exposes those packages to your agent via the Model Context Protocol: no manual copy-paste required.

Which clients work

The bridge is a local stdio MCP server. It runs on your own machine and reads packages from your own disk, so it works with any agent that can launch a local MCP server: Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf, Zed and others. Configuration formats differ (JSON for most, TOML for Codex), but the command is always the same.

ChatGPT is the exception. Apps and plugins in ChatGPT only accept remote HTTPS MCP endpoints, never a local stdio process, so the bridge cannot be installed there. Serving it remotely would mean uploading your session data to a hosted server, which is exactly what TraceGist’s local-first design exists to avoid. If you work in ChatGPT, export a session and paste the handoff markdown into the conversation instead: it is a single self-contained file and needs no integration at all. OpenAI’s Codex, which is the coding agent rather than the chat product, does support the bridge and is configured below.

1) Install the MCP bridge

No installation needed for one-off use:

npx -y tracegist-mcp-bridge

Or install globally:

npm install -g tracegist-mcp-bridge

Requires Node.js 18 or later and a C/C++ toolchain; the bridge compiles its bundled whisper.cpp at install time. Xcode CLI tools (macOS) and build-essential (Linux) are commonly already installed; on Windows you’ll typically need to install Visual Studio Build Tools explicitly.

Voice-note transcription

Local Whisper is bundled: no Python, no system ffmpeg. The TraceGist extension records voice notes as 16 kHz mono wav, which whisper.cpp accepts directly.

Default: local Whisper (private, no external calls once set up). Works out of the box. The default model is base.en (~150 MB), auto-downloaded on first use, so that machine needs network access once, but no audio ever leaves it. Override via TRACEGIST_WHISPER_MODEL (e.g. tiny.en, small.en, large-v3).

Optional: OpenRouter (cloud, fastest first response). If you already have an OpenRouter API key for the extension’s “Analyze with AI”, forward the same key to the bridge:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

When OPENROUTER_API_KEY is set, OpenRouter is tried first and local Whisper is the fallback. The bridge logs the active path(s) at startup (Voice transcription path(s): ...).

Troubleshooting: if the first transcription fails with a “command not found” or “failed to convert audio” error, the bundled whisper.cpp didn’t compile during npm install. Install build tools and reinstall:

• macOS: xcode-select --install
• Debian / Ubuntu: sudo apt install build-essential
• Windows: install Visual Studio Build Tools (the “Desktop development with C++” workload), then re-open your shell

On macOS 26 (Tahoe), a freshly installed Command Line Tools package may not expose the libc++ headers on the default clang++ search path, causing the whisper.cpp build to fail with fatal error: 'vector' file not found. If you hit this, set SDKROOT so clang++ finds the SDK headers:

echo 'export SDKROOT="$(xcrun --show-sdk-path)"' >> ~/.zshrc
source ~/.zshrc

Then re-run npm install (or whichever command triggers the bridge install).

2) Add to your agent config

Claude Code

Run this once in your terminal:

claude mcp add tracegist -- npx -y tracegist-mcp-bridge@latest

OpenAI Codex (CLI, IDE extension and desktop app)

Codex reads MCP servers from ~/.codex/config.toml (global) or .codex/config.toml inside a trusted project directory. Add the bridge interactively:

codex mcp add tracegist -- npx -y tracegist-mcp-bridge@latest

Or write the config yourself:

[mcp_servers.tracegist]
command = "npx"
args = ["-y", "tracegist-mcp-bridge@latest"]
# Optional, if you export somewhere other than ~/Downloads:
# env = { TRACEGIST_DIR = "~/Downloads/tracegist" }
# Bump this if the first call times out while npx fetches the package:
# startup_timeout_sec = 30

Note the key is mcp_servers with an underscore, not the mcpServers spelling used by the JSON clients below. Start a session and run /mcp to confirm the server connected and its tools are listed.

If Codex cannot start the server, the usual cause is npx not being on the PATH that Codex inherits; use an absolute path to npx in that case.

Claude Desktop / other agents

Add this to your claude_desktop_config.json (or equivalent MCP config for your agent):

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart your agent after saving the config.

Custom package directory

By default the bridge searches ~/Downloads for TraceGist packages. Set the TRACEGIST_DIR environment variable to change this:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "TRACEGIST_DIR": "~/Downloads/tracegist"
      }
    }
  }
}

If you configure a custom directory, make the extension save there too: open the viewer’s settings and use Export Folder → Choose folder….

• A folder inside Downloads (for example Downloads/tracegist) is the dependable choice. Packages are saved there without any further permission, however a recording is stopped, and the settings show the full path to copy into TRACEGIST_DIR. If you later rename or move that folder, packages keep going to a folder of the old name; choose the new one again.
• A folder anywhere else depends on Chrome’s access to it, which ends when the last TraceGist tab closes. Choose Allow on every visit when Chrome asks. Whenever access is missing, packages go to Downloads/<folder name> instead, where the bridge is not looking.

Earlier versions had a Download Subfolder setting. It is gone, and its stored value is ignored: if your TRACEGIST_DIR points at that subfolder, choose it as the Export Folder.

3) Export a session

In the TraceGist viewer, use Copy to Coding Agent (header) or Export Session Report (footer). The package ZIP lands in your Downloads folder, or in the export folder you chose.

4) Ask your agent

Once the bridge is connected, your agent can:

• List available TraceGist packages
• Read the handoff markdown and manifest
• Inspect network requests, interaction logs, and screenshots
• Transcribe voice notes (via OpenRouter or local Whisper: see above)
• Build a draft issue payload for Linear / GitHub / Jira via get_tracegist_issue_draft

Example prompt:

Read the latest TraceGist session package and summarise what went wrong.

MCP tools exposed

Live shadowing

Live shadowing lets an agent watch a recording session in real time and interact with the tester as they work.

Enable it: In the TraceGist extension settings, turn on Stream session events to MCP bridge for real-time agent collaboration. When recording starts, a startup prompt is copied to your clipboard; paste it into your agent to begin.

Workflow:

1. Agent calls watch_live_session every few seconds to receive console, network, error, and interaction events as they happen.
2. Agent calls get_live_screenshot to see what the tester is currently looking at.
3. Agent calls ask_tester_question to surface a question as a toast in the tester’s browser (max 500 characters).
4. Tester responds with a voice marker (Alt/Option + Shift + M) and/or a highlight capture (Alt/Option + Shift + S); agent retrieves the answer with get_tester_response.

Remote Live Sessions (tester and developer on different machines)

The same live loop works across the internet through a relay, end-to-end encrypted (AES-256-GCM; key derived from the session code; the relay only ever sees ciphertext; protocol details in docs/live-protocol.md).

Tester (any machine, no MCP setup needed):

1. In the extension popup, click Test with a remote agent and accept the consent screen.
2. Send the generated session code (TG-XXXXX-XXXXX-XXXXX) to the developer.
3. Start recording; a toast confirms the remote session is live.

Developer:

1. Tell your agent: “Join my TraceGist session with code TG-XXXXX-XXXXX-XXXXX”; it calls join_live_session.
2. From there, the workflow is identical to local live shadowing (steps above).
3. leave_live_session disconnects when done.

Relay configuration: the default relay is used unless overridden. To self-host, run npx -y tracegist-relay (or use its Docker image) and set:

• Extension: Settings → Remote Session Relay URL (e.g. wss://relay.example.com)
• Bridge: TRACEGIST_RELAY_URL=wss://relay.example.com in the MCP server env