MCP

Connect your AI tool to Respan logs, traces, prompts, and monitors.

Connect Respan to your AI tool to investigate requests and traces, manage prompts, and configure monitors.

Connect your AI tool

Add https://mcp.respan.ai/mcp and sign in with your Respan account.

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.

Go to chatgpt.com/plugins , click +, and choose Add custom MCP server.
Name it Respan and enter https://mcp.respan.ai/mcp as the server URL.
Choose OAuth for authentication, review the warning, and select I understand and want to continue.
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 mcp add --transport http --scope user respan https://mcp.respan.ai/mcp

Then run /mcp in Claude Code, choose respan, and sign in.

Add this to ~/.cursor/mcp.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 mcp add respan --url https://mcp.respan.ai/mcp
codex mcp login respan

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.

Try a query

Ask your agent:

“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. Keep Read enabled. Enable Write only if the agent should change data.

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 mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \
  --header "Authorization: Bearer $RESPAN_API_KEY"

Add this to ~/.cursor/mcp.json:


{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  }
}


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 mcp add --transport http --scope user respan https://mcp.respan.ai/mcp \
  --header "Authorization: Bearer $RESPAN_API_KEY"

Most clients take this shape:


{
  "mcpServers": {
    "respan": {
      "url": "https://mcp.respan.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  }
}

Tool categories

Category	Use it to
Logs and traces	Find requests and inspect complete runs.
Behaviors and errors	Investigate flagged answers, error groups, and incidents.
Metrics	Compare cost, latency, tokens, and usage.
Prompts	Edit, version, and deploy prompts.
Monitors	Configure alerts and inspect delivered notifications.
Workspace	List and switch organizations with OAuth.

Behavior queries default to whole traces. Ask for individual spans when investigating gateway requests.

Limit the tools

Add Respan-Enabled-Tools to expose only the tools you need. For read-only logs and traces:


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"

API keys are limited to their project. Switching organizations and changing behavior settings require OAuth.

Respan Enterprise

Replace the server URL with https://mcp.respan.ai/mcp/enterprise.

Docs MCP

To search the documentation without accessing project data, add the public docs server. No sign-in is required.


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

For other clients, use https://mcp.respan.ai/mcp/docs with no authentication headers.

Troubleshooting

Problem	Fix
No sign-in prompt	Remove the `Authorization` header for OAuth. In Cursor, include the `auth` block above.
Authentication error	Sign in again, or check that your API key has Read access.
Wrong project’s data	With OAuth, ask the agent to switch organizations. With an API key, use a key from the intended project.

Use the same tools from the terminal

Use the Respan CLI:


respan tools list --json
respan tools call log_list --input '{"page_size":5,"environment":"prod"}'