> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStack MCP server

> Connect AI assistants to ClickStack using the Model Context Protocol (MCP) server

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

ClickStack includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants interact with your observability data. Once connected, an AI assistant can query logs, traces, and metrics; manage dashboards and alerts; explore data sources; and work with saved searches — all through natural language.

This allows you to use tools like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://www.cursor.com/), or any MCP-compatible client to investigate incidents, build dashboards, and manage your observability setup without leaving your development environment.

<h2 id="availability">
  Availability
</h2>

The MCP server is available in the following ClickStack deployment types:

| Deployment                                        | Status        |
| ------------------------------------------------- | ------------- |
| **Open Source ClickStack**                        | Available     |
| **BYOC (Bring Your Own Cloud)**                   | Available     |
| **Managed ClickStack**                            | Coming soon   |
| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Not supported |

<Info>
  **Managed ClickStack**

  MCP server support for Managed ClickStack is under active development and will be available soon. The instructions on this page apply to Open Source and BYOC deployments.
</Info>

<h2 id="prerequisites">
  Prerequisites
</h2>

Before connecting an MCP client, you need:

* A running ClickStack instance (see [Deployment](/clickstack/deployment/overview) for setup options)
* A **Personal API Access Key** — find yours in HyperDX under **Team Settings → API Keys → Personal API Access Key**

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-3a82795f/aRvsybqUpVR5ZXyi/images/clickstack/api-key-personal.png?fit=max&auto=format&n=aRvsybqUpVR5ZXyi&q=85&s=72cc1e86a82b0078bfafd1fb338ebfb4" alt="Personal API Access Key in Team Settings" size="md" border width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

<Note>
  The Personal API Access Key is different from the **Ingestion API Key** found in Team Settings, which is used to authenticate telemetry data sent to the OpenTelemetry collector.
</Note>

<h2 id="endpoint">
  Endpoint
</h2>

The MCP server is available at the `/api/mcp` path on your ClickStack frontend URL:

For example, with a default local deployment:

Replace `localhost:8080` with your instance's host and port if you have customized the defaults.

<Note>
  The examples on this page use the frontend app URL (port `8080` by default). You can also reach the MCP server directly via the backend at `<BACKEND_URL>/mcp`, but not all deployments expose the backend, so these docs use the frontend path.
</Note>

The MCP server uses the **Streamable HTTP** transport with **Bearer token** authentication.

<h2 id="connecting-a-client">
  Connecting an MCP client
</h2>

The examples below show how to configure popular MCP clients. Replace `<YOUR_CLICKSTACK_URL>` with your instance URL (for example, `http://localhost:8080`) and `<YOUR_API_KEY>` with your Personal API Access Key.

<h3 id="claude-code">
  Claude code
</h3>

```shell theme={null}
claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

<h3 id="cursor">
  Cursor
</h3>

Add the following to `.cursor/mcp.json` in your project or your global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<h3 id="opencode">
  OpenCode
</h3>

Add the following to your `opencode.json` config:

```json theme={null}
{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<h3 id="other-clients">
  Other clients
</h3>

Any MCP client that supports the **Streamable HTTP** transport can connect. Configure it with:

* **URL:** `<YOUR_CLICKSTACK_URL>/api/mcp`
* **Header:** `Authorization: Bearer <YOUR_API_KEY>`

<h2 id="capabilities">
  What can you do with MCP?
</h2>

Once connected, your AI assistant has access to a range of tools spanning the core areas of ClickStack. These include:

* **Querying data** — Search and aggregate logs, traces, and metrics using ClickStack's query builder, search syntax, or raw SQL.
* **Data sources** — List available data sources, database connections, column schemas, and attribute keys.
* **Dashboards** — Create, update, delete, and inspect dashboards along with their tiles.
* **Alerts** — Create, update, and inspect alerts along with their evaluation history.
* **Saved searches** — Create, update, and inspect reusable saved search definitions.
* **Webhooks** — List available webhook destinations for alert notifications.
* **Teams** — List teams the current user belongs to and identify the active team.

The specific set of tools may expand over time. Your MCP client will automatically discover the available tools when it connects.

<h2 id="multi-team">
  Multi-team usage
</h2>

By default, MCP requests operate in the context of your primary team. If you belong to multiple teams, you can target a specific team by passing the `x-hdx-team` header set to the team's ID alongside your `Authorization` header. If the header is omitted, your primary team is used. If you specify a team you don't belong to, the request is rejected with a `401` error.

Use the team listing tool from your MCP client to discover which teams you have access to and which one is active.

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<Accordion title="I'm getting a 403 authentication error">
  * Verify that you are using the **Personal API Access Key** (not the Ingestion API Key).
  * Confirm the key is included as a `Bearer` token in the `Authorization` header.
  * Check that your ClickStack instance is running and reachable at the URL you configured.
</Accordion>

<Accordion title="I'm being rate limited">
  The MCP server enforces a rate limit of **600 requests per minute** per user. If you exceed this limit, requests will be temporarily rejected. Reduce the frequency of requests or wait before retrying.
</Accordion>

<Accordion title="I'm getting a 401 error with the x-hdx-team header">
  Verify that the team ID is correct and that your user account is a member of that team.
</Accordion>

<Accordion title="I can't connect to the MCP server">
  * Ensure your MCP client supports the **Streamable HTTP** transport. Older clients that only support the stdio transport won't work.
  * If you are running ClickStack locally, confirm the app is accessible at the configured URL (the default is `http://localhost:8080`).
  * For BYOC deployments behind a load balancer or reverse proxy, ensure the `/api/mcp` path isn't being blocked or rewritten.
</Accordion>