ClickStack MCP server

Connect AI assistants to ClickStack using the Model Context Protocol (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
ClickStack on ClickHouse Cloud	Available
HyperDX v1 (hyperdx.io)	Not supported

Different setup for ClickHouse Cloud vs OSS/BYOC

ClickStack on ClickHouse Cloud uses a different endpoint and authentication method than Open Source and BYOC deployments. See the ClickStack on ClickHouse Cloud section below for Cloud-specific setup.

ClickStack on ClickHouse Cloud

ClickStack on ClickHouse Cloud connects through the Cloud MCP endpoint at https://mcp.clickhouse.cloud/clickstack and authenticates with OAuth 2.0. API key authentication is not supported for this endpoint.

Prerequisites

• A running ClickHouse Cloud service with ClickStack enabled
• MCP enabled on the service — open the Cloud console, click Connect, select Connect with MCP, and toggle it on

Endpoint

https://mcp.clickhouse.cloud/clickstack

Authentication uses OAuth 2.0. When your MCP client connects for the first time, it opens a browser window for you to sign in with your ClickHouse Cloud credentials. No API key is needed.

Connecting an MCP client

Each client handles the OAuth flow automatically on first connection.

Claude Code

claude mcp add --transport http clickstack-cloud https://mcp.clickhouse.cloud/clickstack

Launch Claude Code and run /mcp, then select clickstack-cloud to complete the OAuth flow.

Cursor

Add the following to .cursor/mcp.json:

{
  "mcpServers": {
    "clickstack-cloud": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

VS Code

Add the following to .vscode/mcp.json:

{
  "servers": {
    "clickstack-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

OpenCode

Add the following to opencode.json:

{
  "mcp": {
    "clickstack-cloud": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

Other

Any MCP client that supports Streamable HTTP with OAuth can connect. Configure it with:

• URL: https://mcp.clickhouse.cloud/clickstack

Targeting a specific service

Without the x-service-id header, requests default to the first ClickStack service provisioned and used by your account. To target a different service, pass x-service-id: <YOUR_SERVICE_ID> as a header in your MCP client configuration.

Open Source and BYOC

Open Source and BYOC deployments use your ClickStack instance’s built-in MCP endpoint with Bearer token authentication.

Prerequisites

• 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

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. For example, with a default local deployment, the URL is http://localhost:8080/api/mcp. Replace localhost:8080 with your instance’s host and port if you’ve customized the defaults.

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

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:

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

VS Code

Add the following to .vscode/mcp.json:

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

OpenCode

Add the following to opencode.json:

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

Other

Any MCP client that supports Streamable HTTP 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 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.

Multi-team usage (OSS/BYOC)

This applies to Open Source and BYOC deployments only. For ClickStack on ClickHouse Cloud, see Targeting a specific service.

By default, MCP requests operate in the context of your primary team. If you belong to multiple teams, pass 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.

Troubleshooting

ClickStack on ClickHouse Cloud

OAuth flow doesn't complete

• Confirm your MCP client supports OAuth 2.0. Clients that only support Bearer token or stdio transport can’t authenticate with the Cloud endpoint.
• Check that your browser isn’t blocking the OAuth popup or redirect.
• Verify your ClickHouse Cloud account has access to the organization and service.

MCP is enabled but the client can't connect

• Confirm you’re using the ClickStack endpoint (https://mcp.clickhouse.cloud/clickstack), not the general Cloud MCP endpoint (https://mcp.clickhouse.cloud/mcp).
• Verify that MCP is enabled on the service in the Cloud console.

Requests go to the wrong service

Without the x-service-id header, requests default to the first ClickStack service provisioned and used by your account. Pass the header to target a specific service. See Targeting a specific service.

Open Source and BYOC

I'm getting a 403 authentication error

• Verify that you’re 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 are 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 won’t work.
• If you’re 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.