> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helicone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Generate a Helicone API Key">
    1. Go to [Settings → API Keys](https://us.helicone.ai/settings/api-keys) (or [EU](https://eu.helicone.ai/settings/api-keys))
    2. Click **Generate New Key**
    3. Copy your API key
  </Step>

  <Step title="Add to Your MCP Client">
    Add the Helicone MCP server to your client's configuration file:

    <Tabs>
      <Tab title="Claude Desktop">
        **Config file location:**

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

        ```json theme={null}
        {
          "mcpServers": {
            "helicone": {
              "command": "npx",
              "args": ["@helicone/mcp@latest"],
              "env": {
                "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Claude Code">
        **Config file location:**

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

        ```json theme={null}
        {
          "mcpServers": {
            "helicone": {
              "command": "npx",
              "args": ["@helicone/mcp@latest"],
              "env": {
                "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        **Config file location:**

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

        ```json theme={null}
        {
          "mcpServers": {
            "helicone": {
              "command": "npx",
              "args": ["@helicone/mcp@latest"],
              "env": {
                "HELICONE_API_KEY": "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Codex">
        **Config file location:** `~/.codex/config.toml`

        ```toml theme={null}
        [mcp_servers.helicone]
        command = "npx"
        args = ["@helicone/mcp@latest"]

        [mcp_servers.helicone.env]
        HELICONE_API_KEY = "sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx"
        ```
      </Tab>
    </Tabs>

    <Note>
      Replace `sk-helicone-xxxxxxx-xxxxxxx-xxxxxxx-xxxxxxx` with your actual API key.
    </Note>
  </Step>

  <Step title="Restart Your Client">
    Restart your MCP client (Claude Desktop, Cursor, etc.) to load the new configuration.
  </Step>
</Steps>

## 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](https://www.npmjs.com/package/@helicone/mcp) - Package documentation and source
* [Custom Properties](/features/advanced-usage/custom-properties) - Add metadata to your requests for better filtering
* [Sessions](/features/sessions) - Group related requests into sessions
* [User Metrics](/features/advanced-usage/user-metrics) - Track usage by user