Platform MCP

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

The Model Context Protocol (MCP) is a standardized framework that enables AI models to interact with external data sources and tools. It allows for real-time access to your Respan logs, traces, prompts, and customer data directly from your coding environment.

Getting started

Respan provides an MCP server that gives your AI tools direct access to your observability data. The server supports both HTTP streamable (for hosted deployments) and stdio (for local use).

Installation

OAuth (Recommended)
JWT Token
API Key
Local Stdio
Private HTTP (Teams)

Connect directly using your AI tool’s built-in OAuth support. Your tool will open a browser window for you to sign in — no keys or tokens to manage.

Add the MCP server

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

Authenticate

Your tool will open a browser window where you can sign in with Google or email/password. Once authenticated, the connection is established automatically.

This is the recommended setup for most users. No keys to copy, no tokens to manage — just add the server and authenticate in your browser.

Cursor OAuth known issue: Cursor has a known bug where MCP tools appear connected (green dot, tool count visible) but the agent cannot discover or use them. This affects OAuth-based connections. Use the JWT Token or API Key method instead for reliable Cursor setup.

Sign in through the web login page and copy your access token. Useful as a fallback when OAuth doesn’t work in your tool.

Go to mcp.respan.ai/login and sign in with Google or email/password.

Copy your token

After signing in, you’ll see your access token and a ready-to-paste MCP config. Copy either one.

Configure your AI tool

Add to your MCP configuration file:

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

Restart your AI tool

Restart Cursor or Claude Desktop to load the MCP server.

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

Get your API key

Get your Respan API key from platform.respan.ai.

Configure your AI tool

Add to your MCP configuration file:

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

Restart your AI tool

Restart Cursor or Claude Desktop to load the MCP server.

Run the MCP server locally via stdio — for personal development or offline use.

Prerequisites

Node.js v18 or higher
Git

Clone and build the project

git clone https://github.com/Repsan/respan-mcp.git
cd respan-mcp
npm install
npm run build

Get your API key

Get your Respan API key from platform.respan.ai.

Configure your AI tool

Add to your MCP configuration file. Important: Replace the path with your actual installation path.

{
  "mcpServers": {
    "respan": {
      "command": "node",
      "args": ["/Users/yourname/respan-mcp/dist/lib/index.js"],
      "env": {
        "RESPAN_API_KEY": "your_respan_api_key"
      }
    }
  }
}

Restart your AI tool

Restart Cursor or Claude Desktop to load the MCP server.

After updating the code, run npm run build again and restart your AI tool.

Deploy your own instance to Vercel with your API key stored as an environment variable. Perfect for teams — no client-side keys needed.

Deploy to Vercel

Click to deploy with one click:

Or deploy manually:

git clone https://github.com/Repsan/respan-mcp.git
cd respan-mcp
vercel deploy --prod

Set environment variable

In Vercel Dashboard → Your Project → Settings → Environment Variables:

Add RESPAN_API_KEY = your_respan_api_key
Redeploy for changes to take effect

Configure your AI tool

Share this config with your team (replace with your Vercel URL):

{
  "mcpServers": {
    "respan": {
      "url": "https://your-project.vercel.app/mcp"
    }
  }
}

This mode is ideal for teams — deploy once, and everyone can use the same URL without exposing API keys in their local config.

Authentication

Method	How it works	Best For
OAuth	Tool opens browser for sign-in	Claude Code, Claude Desktop, Codex
JWT Token	Sign in at mcp.respan.ai/login, copy token	Fallback when OAuth fails
API Key	Use key from platform.respan.ai	Programmatic access, scripts
Local Stdio	`RESPAN_API_KEY` env var	Personal development, offline use
Private HTTP	Vercel environment variable	Teams, shared access

Enterprise configuration

Enterprise users have a dedicated MCP endpoint that automatically routes to the enterprise API (endpoint.respan.ai). Use https://mcp.respan.ai/mcp/enterprise instead of https://mcp.respan.ai/mcp.

OAuth
JWT Token
API Key
Local Stdio

Connect using OAuth with the enterprise endpoint. Your tool will open a browser window for enterprise sign-in.

claude mcp add --transport http respan https://mcp.respan.ai/mcp/enterprise

Cursor OAuth known issue: Cursor has a known bug where MCP tools appear connected but the agent cannot discover or use them. Use the JWT Token or API Key method instead for reliable Cursor setup.

Go to mcp.respan.ai/login?enterprise=true and sign in with Google or email/password.

Copy your token

After signing in, you’ll see your access token and a ready-to-paste MCP config. Copy either one.

Configure your AI tool

Add to your MCP configuration file:

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

Use your enterprise Respan API key directly.

Get your API key

Get your API key from enterprise.respan.ai.

Configure your AI tool

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

For local development, set the RESPAN_API_BASE_URL environment variable to point to the enterprise API.

{
  "mcpServers": {
    "respan": {
      "command": "node",
      "args": ["/path/to/respan-mcp/dist/lib/index.js"],
      "env": {
        "RESPAN_API_KEY": "your_respan_api_key",
        "RESPAN_API_BASE_URL": "https://endpoint.respan.ai/api"
      }
    }
  }
}

Endpoint	MCP URL	API URL
Default (Cloud)	`https://mcp.respan.ai/mcp`	`https://api.respan.ai/api`
Enterprise	`https://mcp.respan.ai/mcp/enterprise`	`https://endpoint.respan.ai/api`

Available tools

Once connected, your AI tools have access to the following Respan features.

Logs

Tool	Description
`list_logs`	List and filter LLM request logs with powerful query capabilities
`get_log_detail`	Retrieve complete details of a single log by unique ID

Example queries:

“Show me the most expensive requests from the last hour”
“Find all failed requests for customer user_123”
“List logs where latency > 5 seconds”

Traces

Tool	Description
`list_traces`	List and filter traces with sorting and pagination
`get_trace_tree`	Retrieve complete hierarchical span tree of a trace

Example queries:

“Show me traces with errors in production”
“Get the span tree for trace xyz123”
“Find traces that cost more than $0.10”

Customers

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

Example queries:

“Who are my top 10 customers by cost?”
“Show customer budget usage for user_abc”
“List customers sorted by number of requests”

Prompts

Tool	Description
`list_prompts`	List all prompts in your organization
`get_prompt_detail`	Get detailed prompt information
`list_prompt_versions`	List all versions of a prompt
`get_prompt_version_detail`	Get specific version details

Example queries:

“Show me all my prompts”
“Get the latest version of my customer-support prompt”
“What are the different versions of prompt xyz?”

Troubleshooting

MCP server not showing in Cursor/Claude Desktop

Verify your config file path is correct
Check JSON syntax (use a JSON validator)
Restart your AI tool completely (not just reload)
For stdio mode: ensure npm run build completed successfully

Authentication errors

OAuth: Try signing out and re-authenticating. If OAuth keeps failing in Cursor, use the JWT Token or API Key method instead.
JWT Token: Tokens expire — sign in again at mcp.respan.ai/login to get a fresh token.
API Key: Verify your API key is correct and the header is Authorization: Bearer YOUR_KEY (not just the key).
Stdio mode: Check the RESPAN_API_KEY env var is set correctly.

Connection timeout or errors

Check your internet connection
For enterprise: verify RESPAN_API_BASE_URL is correct
For private HTTP: ensure Vercel deployment is active

Source code

The Respan MCP server is open source:

GitHub Repository

View source code, report issues, and contribute

Get started

Features

Admin

Security

Resources

Help & Community

Platform MCP

Getting started

Installation

Authentication

Enterprise configuration

Available tools

Logs

Traces

Customers

Prompts

Troubleshooting

Source code

GitHub Repository

Get started

Features

Admin

Security

Resources

Help & Community

​Getting started

​Installation

​Authentication

​Enterprise configuration

​Available tools

​Logs

​Traces

​Customers

​Prompts

​Troubleshooting

​Source code

GitHub Repository

Getting started

Installation

Authentication

Enterprise configuration

Available tools

Logs

Traces

Customers

Prompts

Troubleshooting

Source code