> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Connect your coding agent to Bitfab via Model Context Protocol

Bitfab provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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

<CardGroup cols={2}>
  <Card title="TypeScript" icon="js" href="/typescript-sdk">
    `bitfab` -- withSpan wrapper
  </Card>

  <Card title="Python" icon="python" href="/python-sdk">
    `bitfab-py` -- @span decorator
  </Card>

  <Card title="Ruby" icon="gem" href="/ruby-sdk">
    `bitfab` -- bitfab\_span macro
  </Card>

  <Card title="Go" icon="golang" href="/go-sdk">
    `bitfab-go` -- Start/End spans
  </Card>
</CardGroup>

## Quick Setup

### CLI

The fastest way to get connected:

```bash theme={null}
npx bitfab-cli init
```

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](https://bitfab.ai/setup):

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](https://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](/api-keys) for detailed key management instructions.

### Cursor

Add this to your `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

```json theme={null}
{
  "mcpServers": {
    "bitfab": {
      "type": "streamable-http",
      "url": "https://bitfab.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

<Tip>
  Replace `YOUR_API_KEY` with your actual API key, or use the pre-configured setup from the [setup page](https://bitfab.ai/setup).
</Tip>

### Claude Code

Install the Bitfab plugin, which automatically configures the MCP connection and provides slash commands for setup, labeling, and diagnostics:

```bash theme={null}
npx bitfab-cli init
```

Or manually add the marketplace and install:

```
> /plugin marketplace add Project-White-Rabbit/bitfab-claude-plugin
> /plugin install bitfab
> /exit
```

Then restart Claude Code (`claude --continue`) and run `/bitfab:setup`.

### Codex

Set your API key as an environment variable:

```bash theme={null}
export BITFAB_API_KEY="YOUR_API_KEY"
```

Then add this to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-level):

```toml theme={null}
[mcp_servers.bitfab]
url = "https://bitfab.ai/mcp"
bearer_token_env_var = "BITFAB_API_KEY"
```

### Windsurf

Add this to your MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "bitfab": {
      "serverUrl": "https://bitfab.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## 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:

```
Set up Bitfab tracing for my project
```

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

<Tip>
  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.
</Tip>

## 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](https://bitfab.ai/setup) 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](/api-keys)
* **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](/api-keys) for key management
2. Visit the [setup page](https://bitfab.ai/setup) for automatic configuration
3. Contact support if the issue persists