Helicone MCP Server

Query your Helicone observability data directly from MCP-compatible AI assistants using the 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

1. Generate a Helicone API Key

   1. Go to Settings → API Keys (or EU)
   2. Click Generate New Key
   3. Copy your API key
2. Add to Your MCP Client

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

   Claude Desktop

   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"
         }
       }
     }
   }
   

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

3. 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

Related Resources

• @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