> 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 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 In Claude on the web or Claude Desktop: 1. Go to **Customize** › **Connectors** and click **Add**. 2. Hover over **Custom** and select **Web**. 3. Name it `Respan`, enter `https://mcp.respan.ai/mcp`, and click **Continue**. 4. Keep the detected sign-in settings, click **Add**, and sign in to Respan. 5. 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. #### ChatGPT 1. Go to [chatgpt.com/plugins](https://chatgpt.com/plugins), click **+**, and choose **Add custom MCP server**. 2. Name it `Respan` and enter `https://mcp.respan.ai/mcp` as the server URL. 3. Choose OAuth for authentication, review the warning, and select **I understand and want to continue**. 4. Select **Create as a plugin**, then sign in to Respan. Whether you can add custom MCP servers depends on your ChatGPT plan. In Business and Enterprise workspaces, an admin may need to allow them. #### Claude Code ```bash claude mcp add --transport http --scope user respan https://mcp.respan.ai/mcp ``` Then run `/mcp` in Claude Code, choose **respan**, and sign in. To also get the Respan skill, which teaches Claude Code how to set up tracing, the gateway, prompts, and evals, install the Respan plugin instead. It asks for an [API key](#use-an-api-key-instead) during install: ``` /plugin marketplace add respanai/respan /plugin install respan@respan ``` #### Cursor Add this to `~/.cursor/mcp.json`: ```json { "mcpServers": { "respan": { "url": "https://mcp.respan.ai/mcp", "auth": { "CLIENT_ID": "enc_mQcqjLKvweUikLjRuWfTCem2CVwhJl39wSNfEOmSpuW7Pd02UtUaoL4vR5JdIwXelPmuap6S6Bmow7L3MY4Z_vbKz375X6T71R7sRdTBxPoDrYsCepi-7kqNGwPLwx9a9ucFaqAff1hPF4lNfXj6oeHSKspd8ci7TgU-Y813M_ZZ2P7qcKpjcsWuv2vZJsiZUyNL5rTIDdwbKGQXCCM7f8P_EPuhE5HC6yJ_O0rDy4Y1572C0eECAQusDgBoV5p7HG3LNhGkqsph2-APkgnU9IMgUNrFxofF" } } } } ``` Then sign in to **respan** from Cursor's MCP settings. The `CLIENT_ID` is a public identifier registered for Cursor, not a secret. Without it, Cursor doesn't offer a sign-in and the tools fail. #### Codex ```bash codex mcp add respan --url https://mcp.respan.ai/mcp codex mcp login respan ``` #### Other clients Any client that supports remote (streamable HTTP) MCP servers with OAuth works: add `https://mcp.respan.ai/mcp` and sign in when it asks. For a client without OAuth, [use an API key](#use-an-api-key-instead). 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](https://platform.respan.ai), 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: ```bash export RESPAN_API_KEY="your-respan-api-key" ``` #### Add the server with the key Send the key as a bearer token. #### Claude Code ```bash claude mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \ --header "Authorization: Bearer $RESPAN_API_KEY" ``` #### Cursor Add this to `~/.cursor/mcp.json`: ```json { "mcpServers": { "respan": { "url": "https://mcp.respan.ai/mcp", "headers": { "Authorization": "Bearer YOUR_RESPAN_API_KEY" } } } } ``` #### Codex ```bash codex mcp add respan --url https://mcp.respan.ai/mcp --bearer-token-env-var RESPAN_API_KEY ``` Codex reads the key from `RESPAN_API_KEY` each time it starts, so keep it exported in your shell. #### Gemini CLI ```bash gemini mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \ --header "Authorization: Bearer $RESPAN_API_KEY" ``` #### Other clients Most clients take this shape: ```json { "mcpServers": { "respan": { "url": "https://mcp.respan.ai/mcp", "headers": { "Authorization": "Bearer YOUR_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: ```bash 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`. ```bash 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](https://github.com/respanai/respan-mcp).