MCP | Respan Docs

The Respan MCP server gives your AI tool access to your Respan project: it can query logs, traces, and conversations, look at flagged behaviors and errors, and manage prompts, datasets, evaluators, experiments, and monitors. A second server, the docs MCP, lets it search these docs.

Connect

The server URL is https://mcp.respan.ai/mcp. You sign in to Respan in your browser with Google or email, so there is no key to copy. The tool then acts as you, in your active organization, and can list and switch your organizations for you.

Claude app

ChatGPT

Claude Code

Cursor

Codex

Other clients

In Claude on the web or Claude Desktop:

Go to Customize › Connectors and click Add.
Hover over Custom and select Web.
Name it Respan, enter https://mcp.respan.ai/mcp, and click Continue.
Keep the detected sign-in settings, click Add, and sign in to Respan.
In a chat, click +, hover over Connectors, and turn on Respan.

Custom connectors are available on every Claude plan. Free plans are limited to one.

Then ask something like:

“Show me the 10 most expensive requests from the last hour.”
“Which behaviors fired most this week, and on which models?”
“What are my top errors today? Tell me more about the first one.”
“Deploy the current draft of my customer-support prompt.”

Use an API key instead

Use an API key for scripts, CI, or clients without OAuth. A key only reaches the project it was created in, so the agent can’t switch organizations.

Create an API key

In the platform, go to Gateway › API keys and click New key. The default permissions, Read, Write, and Gateway, cover every MCP tool. Uncheck Write if the agent should only read.

Click Create, then Copy, and save the key:

export RESPAN_API_KEY="your-respan-api-key"

Add the server with the key

Send the key as a bearer token.

Claude Code

Cursor

Codex

Gemini CLI

Other clients

claude mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \
  --header "Authorization: Bearer $RESPAN_API_KEY"

What the agent can do

Tool names match the ones the Respan agent in the platform uses.

Area	Tools
Logs, traces, and conversations	`log_list`, `log_get`, `trace_list`, `trace_get`, `thread_list`, `thread_get`
Usage	`dashboard_llm_metrics_summary`, `dashboard_top_models`, `end_user_rank_by_usage`
Behaviors	`pulse_behaviors_summary`, `behavior_list`, `behavior_timeseries`, `behavior_grouped`, `behavior_spans_list`, and `custom_behavior_*` to suggest, create, update, and delete custom behaviors
Errors	`pulse_error_groups_list`, `pulse_error_group_get`, `pulse_incidents_list`
Prompts	List, read, create, and update prompts and versions, `prompt_commit`, and `prompt_deploy`
Datasets	Create datasets, add rows, `dataset_logs_import` from production, and summarize rows
Graders and evaluators	Create, test (`grader_run`), and commit graders, and build evaluators from them
Experiments	`experiment_create`, list its spans, and `experiment_score_averages`
Monitors, automations, and exports	Create, commit, deploy, and undeploy monitor, automation, and export workflows
Organizations	`org_list`, `org_switch` (OAuth only)

Clients ask you to confirm anything that changes or deletes data, depending on their settings.

Limit the tools

To expose only some tools, add a Respan-Enabled-Tools header with a comma-separated list of tool names:

claude mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \
  --header "Authorization: Bearer $RESPAN_API_KEY" \
  --header "Respan-Enabled-Tools: log_list,log_get,trace_list,trace_get"

Older tool names, such as list_logs and get_trace_tree, still work in this header.

Respan Enterprise

Use https://mcp.respan.ai/mcp/enterprise in place of https://mcp.respan.ai/mcp in any setup above.

Docs MCP

The docs server has one tool, docs_search, and needs no sign-in or key. Its URL is https://mcp.respan.ai/mcp/docs.

claude mcp add --transport http --scope user respan-docs https://mcp.respan.ai/mcp/docs

In other clients, add it the same way as the platform server, with this URL and no headers.

Troubleshooting

Problem	Fix
The server doesn’t show up	Check the config file path and JSON, then fully restart the client.
The client never asks you to sign in	Remove any `Authorization` header from its config. In Cursor, include the `auth` block shown above.
Tools return an authentication error	Sign in again. With an API key, the key is wrong, revoked, or missing Read: create a new one.
The agent only sees part of your data	It works in one organization at a time. Ask it to list and switch organizations (OAuth only).

The server is open source: respanai/respan-mcp.