Helicone MCP Server

The Helicone MCP (Model Context Protocol) server enables AI assistants like Claude Desktop, Cursor, and other MCP-compatible tools to query your Helicone observability data directly. This allows you to debug errors, search logs, analyze performance, and examine request/response bodies without leaving your AI assistant.

Quick Start

Generate a Helicone API Key

Go to Settings → API Keys (or EU)
Click Generate New Key
Copy your API key

Add to Your MCP Client

Add the Helicone MCP server to your client’s configuration file:

Claude Desktop
Claude Code
Cursor
Codex

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "helicone": {
      "command": "npx",
      "args": ["@helicone/mcp@latest"],
      "env": {
        "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
      }
    }
  }
}

Config file location:

Project-level: .mcp.json in your project root
Global: ~/.claude.json

{
  "mcpServers": {
    "helicone": {
      "command": "npx",
      "args": ["@helicone/mcp@latest"],
      "env": {
        "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
      }
    }
  }
}

Config file location:

macOS/Linux: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "helicone": {
      "command": "npx",
      "args": ["@helicone/mcp@latest"],
      "env": {
        "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
      }
    }
  }
}

Config file location: ~/.codex/config.toml

[mcp_servers.helicone]
command = "npx"
args = ["@helicone/mcp@latest"]

[mcp_servers.helicone.env]
HELICONE_API_KEY = "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"

Replace sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx with your actual API key.

Restart Your Client

Restart your MCP client (Claude Desktop, Cursor, etc.) to load the new configuration.

Available Tools

`query_requests`

Query requests with filters, pagination, sorting, and optional body content. Parameters:

Parameter	Type	Description
`filter`	object	Filter criteria (model, provider, status, latency, cost, properties, time, user, etc.)
`offset`	number	Pagination offset (default: 0)
`limit`	number	Number of results to return (default: 100)
`sort`	object	Sort criteria
`includeBodies`	boolean	Include request/response bodies (default: false)

Example use cases:

“Show me the last 10 failed requests”
“Find all requests to GPT-4 in the last hour”
“Search for requests with high latency”
“Show me requests from a specific user”

`query_sessions`

Query sessions with search, time range filtering, and advanced filters. Parameters:

Parameter	Type	Description
`startTimeUnixMs`	number	Start of time range (Unix timestamp in milliseconds) - required
`endTimeUnixMs`	number	End of time range (Unix timestamp in milliseconds) - required
`timezoneDifference`	number	Timezone offset in hours (e.g., -5 for EST) - required
`search`	string	Search by name or metadata
`nameEquals`	string	Exact session name match
`filter`	object	Advanced filter criteria
`offset`	number	Pagination offset (default: 0)
`limit`	number	Number of results to return (default: 100)

Example use cases:

“Show me all sessions from today”
“Find sessions named ‘checkout-flow’”
“Debug conversation flows in a specific time range”
“Analyze session performance metrics”

Filter Capabilities

Both tools support comprehensive filtering options:

Model/Provider: Filter by specific models or providers
Status/Error: Find successful or failed requests
Time: Filter by time ranges
Cost/Latency: Filter by performance metrics
Custom Properties: Filter by your custom Helicone properties
Complex Filters: Combine filters with AND/OR logic

@helicone/mcp on npm - Package documentation and source
Custom Properties - Add metadata to your requests for better filtering
Sessions - Group related requests into sessions
User Metrics - Track usage by user

Getting Started

AI Gateway

Observability & Analytics

Prompt Management

Legacy Integrations

References

Quick Start

Available Tools

`query_requests`

`query_sessions`

Filter Capabilities

​Quick Start

​Available Tools

​query_requests

​query_sessions

​Filter Capabilities

​Related Resources

Quick Start

Available Tools

`query_requests`

`query_sessions`

Filter Capabilities

Related Resources