Skip to main content
Bitfab provides an MCP (Model Context Protocol) server that lets coding agents like Cursor, Claude Code, Codex, and Windsurf set up Bitfab tracing in your codebase automatically. The MCP server provides tools for setup, trace inspection, datasets, labels, experiments, templates, and database-backed replay. Core setup tools include:
  • get_bitfab_api_key — Retrieves your API key for the agent to configure
  • get_api_key_context — Returns which Bitfab org the connection reads/writes to. Useful when data written by the agent isn’t visible in Studio (the org may differ from the project’s BITFAB_API_KEY or the org open in the browser)
  • list_organizations — Lists the organizations available to the signed-in user and marks the current plugin org
  • get_database_connection_status — Reports whether the org has connected a database for per-trace replay branching
SDK setup content (install commands, initialization, instrumentation patterns, and replay) lives in the language-specific SDK reference pages on this site (TypeScript, Python, Ruby, Go). Agents fetch those pages directly rather than through an MCP tool.

​
API Key Requirements

The MCP server requires authentication to access your organization’s API keys and provide personalized setup guidance. You have two options:
  1. Automatic Authentication (Recommended): Use the setup page which automatically configures authentication
  2. Manual Configuration: Add authentication headers to your MCP client configuration

​
Supported Languages

TypeScript

bitfab — withSpan wrapper

Python

bitfab-py — @span decorator

Ruby

bitfab — bitfab_span macro

Go

bitfab-go — Start/End spans

​
Quick Setup

​
CLI

The fastest way to get connected:
Detects your editor, installs the plugin, authenticates, and launches setup. Works with Claude Code, Codex, and Cursor. The CLI checks that your editor’s own agent is signed in before launching Bitfab setup (claude auth login, codex login, or cursor agent login).

​
Setup Page

For agents not supported by the CLI, or if you prefer manual configuration, use the Bitfab setup page:
  1. Choose your agent: The page shows setup instructions for Claude Code, Cursor, Codex, and other MCP clients
  2. Follow the steps: Claude Code uses a plugin install flow; other agents use MCP configuration with your API key embedded
  3. Copy and paste: Each configuration is ready to use — no manual key copying needed
The setup page provides:
  • Claude Code: Plugin install commands that handle MCP setup and authentication automatically
  • Cursor: One-click deep link installation
  • Other agents: Ready-to-use MCP configuration with your API key embedded

​
Manual Configuration

If you prefer to set up the MCP connection manually, you’ll need to include your API key in the configuration.

​
Getting Your API Key

  1. From the setup page: Visit bitfab.ai/setup and copy your API key
  2. From the dashboard: Click your profile avatar → API Keys → Create/view your key
See the API Keys guide for detailed key management instructions.

​
Cursor

Add this to your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):
Replace YOUR_API_KEY with your actual API key, or use the pre-configured setup from the setup page.

​
Claude Code

Install the Bitfab plugin, which automatically configures the MCP connection and provides slash commands for setup, labeling, and diagnostics:
Or manually add the marketplace and install:
Then restart Claude Code (claude --continue) and run /bitfab:setup.

​
Codex

Set your API key as an environment variable:
Then add this to ~/.codex/config.toml (global) or .codex/config.toml (project-level):

​
Windsurf

Add this to your MCP configuration:

​
How It Works

Once connected, your coding agent can:
  1. Call get_bitfab_api_key to retrieve your API key (requires your Bitfab session)
  2. Call get_api_key_context to confirm which org the connection targets (helpful when data isn’t showing up in the expected place)
  3. Fetch the language-specific SDK reference from this site (e.g. https://docs.bitfab.ai/typescript-sdk) to get the full API surface, install commands, instrumentation patterns, and replay setup
  4. Follow the reference to install the SDK, initialize the client, and instrument your functions

​
Example Workflow

Ask your coding agent:
The agent will:
  1. Detect your project language
  2. Call get_bitfab_api_key to get the API key and get_api_key_context to confirm the target org, then fetch the language-specific SDK reference from docs.bitfab.ai
  3. Install the SDK
  4. Read your codebase and identify all AI workflows
  5. Present you with a list of workflows it found, and why each is worth instrumenting
  6. Instrument whichever workflows you choose, one, several, or all
The agent presents options and lets you choose which workflows to instrument, so you stay in control. Each option explains what visibility tracing gives you into that workflow.

​
Troubleshooting

​
Authentication Issues

If your agent can’t access the MCP tools:
  1. Check your API key: Ensure you’re using the correct API key from your dashboard
  2. Verify the header format: Use Authorization: Bearer YOUR_API_KEY (note the space after “Bearer”)
  3. Organization access: Make sure you’re logged into the correct organization in Bitfab
  4. Try the setup page: Use the automatic configuration to avoid manual errors

​
Connection Problems

Common issues and solutions:
  • MCP server not found: Verify the URL is https://bitfab.ai/mcp. If using Claude Code with the Bitfab plugin, run /bitfab:setup to reconfigure.
  • Tools not available: Restart your coding agent after adding the MCP configuration
  • API key errors: Generate a new API key from the API Keys page
  • Network issues: Ensure your network allows HTTPS connections to bitfab.ai

​
Getting Help

If you’re still having trouble:
  1. Check the API Keys documentation for key management
  2. Visit the setup page for automatic configuration
  3. Contact support if the issue persists