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

# ClickStack MCP server

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

The ClickStack MCP server uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](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.

[YouTube video player](https://www.youtube.com/embed/FaL5iOgNogg?si=dUbsRQe4wYuZ78zt)

## 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](https://clickhouse.com/docs/clickstack/observability/getting-started.md)
* [MCP enabled](https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp.md#enable-remote-mcp-server) on the service — open the Cloud console, click **Connect**, select **Connect with MCP**, and toggle it on

### Endpoint

```text theme={null}
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

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.

> [tab] Claude Code
>
> ```shell theme={null}
> claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack
> ```
>
> Launch Claude Code and run `/mcp`, then select `clickstack` to complete the OAuth flow.

> [tab] Cursor
>
> Add the following to `.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "clickstack": {
>       "url": "https://mcp.clickhouse.cloud/clickstack"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Add the following to `.vscode/mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "clickstack": {
>       "type": "http",
>       "url": "https://mcp.clickhouse.cloud/clickstack"
>     }
>   }
> }
> ```

> [tab] OpenCode
>
> Add the following to `opencode.json`:
>
> ```json theme={null}
> {
>   "mcp": {
>     "clickstack": {
>       "type": "remote",
>       "url": "https://mcp.clickhouse.cloud/clickstack"
>     }
>   }
> }
> ```

> [tab] LibreChat
>
> Add the following to `librechat.yaml`:
>
> ```yaml theme={null}
> mcpServers:
>   clickstack:
>     type: streamable-http
>     url: https://mcp.clickhouse.cloud/clickstack
> ```

> [tab] 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 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

> [accordion] 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.

> [accordion] MCP is enabled but the client can't connect
>
> * 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](https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp.md#enable-remote-mcp-server) on the service in the Cloud console.

> [accordion] Requests go to the wrong service
>
> 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](#managed-service-override).