> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# MCP

## Platform MCP

The Platform MCP server gives your AI tools direct access to your Respan observability data -- logs, traces, prompts, customers, and more.

## Setup

#### API Key (Recommended)

Use your Respan API key. Works with any MCP client.

Get your API key from [platform.respan.ai](https://platform.respan.ai/platform/api/api-keys), then add the config to your tool:

```bash Claude Code
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  respan \
  https://mcp.respan.ai/mcp
```

```json Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  }
}
```

```json Codex CLI (~/.codex/config.toml)
[mcp_servers.respan]
enabled = true
url = "https://mcp.respan.ai/mcp"

[mcp_servers.respan.http_headers]
Authorization = "Bearer YOUR_RESPAN_API_KEY"
```

Restart your tool to load the MCP server.

#### OAuth

Connect using your tool's built-in OAuth support. Your tool opens a browser window for sign-in - no keys to manage.

```bash Claude Code
claude mcp add --transport http respan https://mcp.respan.ai/mcp
```

```json Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/mcp"
    }
  }
}
```

```json Codex CLI (~/.codex/config.toml)
[mcp_servers.respan]
enabled = true
url = "https://mcp.respan.ai/mcp"
```

Your tool will open a browser window where you sign in with Google or email/password.

**Cursor OAuth known issue:** Cursor has a [known bug](https://forum.cursor.com/t/agent-has-trouble-detecting-available-mcp-tools/146486) where MCP tools appear connected but the agent cannot use them. Use the **API Key** method for Cursor instead.

### JWT Token (OAuth fallback)

If OAuth doesn't work in your tool, sign in at [mcp.respan.ai/login](https://mcp.respan.ai/login) and copy the access token. Then use the same configs as the **API Key** tab, replacing the API key with your JWT token.

## Optional: whitelist specific tools

If you only want your MCP client to see a subset of tools, add the `Respan-Enabled-Tools` header with a comma-separated list of exact tool names.

If you omit this header, all Platform MCP tools are available.

```bash Claude Code
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  --header "Respan-Enabled-Tools: list_logs,get_log_detail,list_traces,get_trace_tree" \
  respan \
  https://mcp.respan.ai/mcp
```

```json Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY",
        "Respan-Enabled-Tools": "list_logs,get_log_detail,list_traces,get_trace_tree"
      }
    }
  }
}
```

```toml Codex CLI (~/.codex/config.toml)
[mcp_servers.respan]
enabled = true
url = "https://mcp.respan.ai/mcp"

[mcp_servers.respan.http_headers]
Authorization = "Bearer YOUR_RESPAN_API_KEY"
Respan-Enabled-Tools = "list_logs,get_log_detail,list_traces,get_trace_tree"
```

Use exact MCP tool names. For example, setting `Respan-Enabled-Tools: list_logs,list_traces` exposes only those two tools to the client.

## Enterprise

Enterprise users have a dedicated endpoint. Replace `https://mcp.respan.ai/mcp` with `https://mcp.respan.ai/mcp/enterprise` in any config above.

| Endpoint   | MCP URL                                | API URL                     |
| ---------- | -------------------------------------- | --------------------------- |
| Cloud      | `https://mcp.respan.ai/mcp`            | `https://api.respan.ai/api` |
| Enterprise | `https://mcp.respan.ai/mcp/enterprise` | Your enterprise base URL    |

## Available tools

Once connected, your AI tools can access these Platform MCP tools:

### Logs

| Tool                | Description                          |
| ------------------- | ------------------------------------ |
| `list_logs`         | List and filter LLM request logs     |
| `get_log_detail`    | Get complete details of a single log |
| `create_log`        | Create a new log entry               |
| `get_spans_summary` | Get aggregated metrics for log spans |

**Try:** "Show me the most expensive requests from the last hour" or "Find all failed requests for customer user\_123"

### Traces

| Tool                 | Description                       |
| -------------------- | --------------------------------- |
| `list_traces`        | List and filter traces            |
| `get_trace_tree`     | Get the full span tree of a trace |
| `get_traces_summary` | Get aggregated metrics for traces |

**Try:** "Show me traces with errors in production" or "Get the span tree for trace xyz123"

### Customers

| Tool                  | Description                                 |
| --------------------- | ------------------------------------------- |
| `list_customers`      | List customers with sorting and pagination  |
| `get_customer_detail` | Get customer details including budget usage |

**Try:** "Who are my top 10 customers by cost?" or "Show budget usage for user\_abc"

### Prompts

| Tool                        | Description                                   |
| --------------------------- | --------------------------------------------- |
| `list_prompts`              | List all prompts                              |
| `get_prompt_detail`         | Get prompt details                            |
| `list_prompt_versions`      | List all versions of a prompt                 |
| `get_prompt_version_detail` | Get a specific version                        |
| `create_prompt`             | Create a prompt shell                         |
| `update_prompt`             | Update prompt metadata                        |
| `create_prompt_version`     | Create a new prompt version                   |
| `update_prompt_version`     | Update an existing prompt version             |
| `deploy_prompt_version`     | Deploy a committed (readonly) version as live |

**Try:** "Show me all my prompts" or "Deploy version 3 of my customer-support prompt"

### Experiments

| Tool                            | Description                                                                         |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| `list_experiments`              | List all experiments                                                                |
| `get_experiment`                | Get experiment details                                                              |
| `create_experiment`             | Create and run an experiment (prompt, completion, duplicate, or condition workflow) |
| `delete_experiment`             | Delete an experiment and its spans                                                  |
| `list_experiment_spans`         | List spans for an experiment                                                        |
| `get_experiment_span`           | Get a single experiment span                                                        |
| `get_experiment_score_averages` | Compute avg/min/max score per evaluator across an experiment's spans                |

**Try:** "List my recent experiments" or "Compare prompt v3 vs v4 on the customer-support dataset"

### Evaluators

| Tool                      | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `list_evaluators`         | List all evaluators (graders)                    |
| `get_evaluator`           | Get evaluator details                            |
| `create_evaluator`        | Create a new LLM or code evaluator               |
| `update_evaluator`        | Update an evaluator                              |
| `delete_evaluator`        | Delete an evaluator                              |
| `test_evaluator`          | Run an evaluator against sample inputs (dry-run) |
| `commit_evaluator`        | Lock an evaluator version as readonly            |
| `list_evaluator_versions` | List version history for an evaluator            |
| `run_evaluator`           | Score a single log with an evaluator             |

**Try:** "Create an LLM grader that rates response quality 1-10" or "Run qa-score on log abc123"

### Evaluation pipelines

Pipelines wrap one or more evaluators into a Blockly task graph (single grader, average, weighted average, or conditional gates). Pipelines are what `create_experiment` references via `evaluator_workflow_ids`.

| Tool                         | Description                                                         |
| ---------------------------- | ------------------------------------------------------------------- |
| `list_evaluation_pipelines`  | List all evaluator pipelines                                        |
| `get_evaluation_pipeline`    | Get a pipeline's task graph                                         |
| `create_evaluation_pipeline` | Build a pipeline (single / average / weighted / condition patterns) |
| `update_evaluation_pipeline` | Rebuild a pipeline's task graph                                     |

**Try:** "Create a pipeline that runs my quality grader, then routes scores >7 to a deeper LLM judge"

### Workflows

| Tool                                    | Description                                    |
| --------------------------------------- | ---------------------------------------------- |
| `list_workflows` / `filter_workflows`   | List or filter workflows                       |
| `get_workflow` / `get_workflow_version` | Get workflow or specific version               |
| `list_workflow_versions`                | List version history                           |
| `create_workflow` / `update_workflow`   | Create / update a workflow                     |
| `commit_workflow`                       | Commit the current draft as a readonly version |
| `deploy_workflow` / `undeploy_workflow` | Deploy / undeploy a committed version          |
| `validate_workflow`                     | Validate workflow structure                    |

### Datasets

| Tool                       | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| `list_datasets`            | List all datasets                                             |
| `get_dataset`              | Get dataset details                                           |
| `create_dataset`           | Create a new dataset (empty, sampling, or copy from existing) |
| `update_dataset`           | Update dataset metadata                                       |
| `delete_dataset`           | Delete a dataset                                              |
| `list_dataset_logs`        | List rows in a dataset                                        |
| `retrieve_dataset_log`     | Get a single dataset row                                      |
| `replace_dataset_log`      | Replace a row's input / output / expected\_output             |
| `bulk_create_dataset_logs` | Insert one or more rows (use this for inserts)                |
| `remove_dataset_logs`      | Remove rows by filter                                         |
| `summarize_dataset_logs`   | Aggregate metrics (cost, latency, scores) across rows         |
| `list_dataset_eval_runs`   | List eval runs against a dataset                              |
| `import_dataset_logs`      | Import logs from production into a dataset                    |

**Try:** "Show me my datasets" or "Insert 5 test rows into dataset ds\_123"

## Troubleshooting

| Issue                  | Fix                                                                 |
| ---------------------- | ------------------------------------------------------------------- |
| MCP server not showing | Check config file path, validate JSON, restart tool completely      |
| OAuth fails            | Try API Key method instead. For Cursor, always use API Key.         |
| JWT token expired      | Sign in again at [mcp.respan.ai/login](https://mcp.respan.ai/login) |
| Connection timeout     | Check internet. For enterprise, verify `RESPAN_API_BASE_URL`.       |

## Source code

The Respan MCP server is open source: [github.com/respanai/respan-mcp](https://github.com/respanai/respan-mcp)

---

## Docs MCP

Give your AI coding tools access to Respan documentation. No API key needed.

```bash Claude Code
claude mcp add --transport http respan-docs https://mcp.respan.ai/mcp/docs
```

```json Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://mcp.respan.ai/mcp/docs"
    }
  }
}
```

```json Codex CLI (~/.codex/config.toml)
[mcp_servers.respan-docs]
enabled = true
url = "https://mcp.respan.ai/mcp/docs"
```

Restart your tool to load the server.

| Tool          | Description                            |
| ------------- | -------------------------------------- |
| `search_docs` | Search across all Respan documentation |

**Try:** "How do I set up Respan tracing with LangGraph?" or "Show me the OpenAI SDK integration docs"