Skip to main content
The ClickStack MCP server uses the Model Context Protocol (MCP) to let AI assistants interact with your ClickHouse 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.

​
Connect to ClickHouse Observability

ClickHouse Observability 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 observability enabled
  • MCP enabled on the service — open the Cloud console, click Connect, select Connect with MCP, and toggle it on

​
Endpoint

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

Open Team Settings → API & Agents in your ClickHouse Observability service to copy a configuration for your MCP client. The generated configuration includes the service ID so requests target that service. Alternatively, use one of the examples below. Your client prompts you to complete OAuth authentication when you connect.
Launch Claude Code and run /mcp, then select clickstack to complete the OAuth flow.

​
Targeting a specific service

Without the x-service-id header, requests default to the first observability 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.

​
What can you do with MCP?

Once connected, your AI assistant has access to a range of tools spanning the core areas of the service. These include:
  • Querying data — Search and aggregate logs, traces, and metrics using the 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.

​
Troubleshooting

  • 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.
  • Confirm you’re using the observability 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.
Without the x-service-id header, requests default to the first observability service provisioned and used by your account. Pass the header to target a specific service. See Targeting a specific service.