MCP server

ClickStack includes a built-in Model Context Protocol (MCP) 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, Cursor, or any MCP-compatible client to investigate incidents, build dashboards, and manage your observability setup without leaving your development environment.

Availability

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)	Not supported

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.

Prerequisites

Before connecting an MCP client, you need:

• A running ClickStack instance (see Deployment for setup options)
• A Personal API Access Key — find yours in HyperDX under Team Settings → API Keys → Personal API Access Key

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.

Endpoint

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

<YOUR_CLICKSTACK_URL>/api/mcp

For example, with a default local deployment:

http://localhost:8080/api/mcp

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.

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

Connecting an MCP client

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.

Claude Code

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Cursor

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

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

OpenCode

Add the following to your opencode.json config:

{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Other clients

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>

What can you do with MCP?

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 and individual dashboard 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.

Multi-team usage

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 do not 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 currently active.

Troubleshooting

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.

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.

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.

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 will not 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 is not being blocked or rewritten.