# MCP Client Setup

Step-by-step setup for connecting Claude Desktop, Cursor, Claude Code, or any MCP-compatible client to your chmonitor deployment.

The server-side reference (endpoint, tools, security model) is at [MCP Server](/reference/mcp-server).

---

## Before you start

You need:

- A running chmonitor instance (Docker, Kubernetes, or Cloudflare Workers).
- The public URL of that instance, e.g. `https://dash.example.com`.
- An API key if auth is enabled (see [Authentication](#authentication) below).

The MCP endpoint is `<your-deployment>/api/mcp`. It uses the **Streamable HTTP** transport — no WebSocket, no persistent session.

---

## Authentication

If `CHM_API_KEY_SECRET` is set on the server, every request must carry a bearer token.

**Issue a token** (once, on the server):

```bash
curl -X POST https://dash.example.com/api/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{"sub": "my-mcp-client"}'
```

The response returns a `chm_` prefixed token. Pass it in the `Authorization` header:

```
Authorization: Bearer chm_<token>
```

Tokens are HMAC-SHA-256 signed and expire after 30 days by default.

If neither `CHM_API_KEY_SECRET` nor Clerk is configured, the endpoint accepts anonymous requests — suitable for a trusted local deployment.

---

## Claude Desktop

Open the config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add an entry under `mcpServers`:

```json
{
  "mcpServers": {
    "clickhouse-monitor": {
      "url": "https://dash.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer chm_your_api_key"
      }
    }
  }
}
```

Omit the `headers` block for an unauthenticated local instance.

Restart Claude Desktop. The `clickhouse-monitor` server should appear in the tools panel.

---

## Claude Code

Run the one-liner in your terminal:

```bash
claude mcp add --transport http clickhouse-monitor https://dash.example.com/api/mcp
```

For authenticated deployments, add the header:

```bash
claude mcp add --transport http clickhouse-monitor https://dash.example.com/api/mcp \
  --header "Authorization: Bearer chm_your_api_key"
```

Verify the server was registered:

```bash
claude mcp list
```

---

## Cursor

**Via Settings UI:** open Cursor Settings (`Cmd+,` on macOS), go to **Features → MCP**, and click **Add MCP Server**. Paste the endpoint URL and set the transport to `http`.

**Via config file** — add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "clickhouse-monitor": {
      "url": "https://dash.example.com/api/mcp",
      "transport": "http"
    }
  }
}
```

If auth is enabled, add a `headers` block (same shape as the Claude Desktop example above).

---

## Any MCP client

The server uses the **Streamable HTTP** transport in stateless mode (`POST /api/mcp`). No session handshake is required.

**Verify connectivity** before configuring your client:

```bash
curl -X POST https://dash.example.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer chm_your_api_key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

A successful response lists the available tools. If you get `401`, the token is missing or invalid.

Point your client at `https://dash.example.com/api/mcp`. The three methods the server handles are `POST`, `GET`, and `DELETE`; it also responds to `OPTIONS` for CORS preflight.

---

## Available tools

Once connected, your AI assistant can use these tools:

| Tool | Description |
|---|---|
| `query` | Execute a read-only SQL query (SELECT only). |
| `list_databases` | List databases with engines and comments. |
| `list_tables` | List tables in a database with row counts and sizes. |
| `get_table_schema` | Column definitions, types, defaults, and comments. |
| `get_metrics` | Server version, uptime, connections, memory. |
| `get_running_queries` | Currently running queries ordered by elapsed time. |
| `get_slow_queries` | Slowest completed queries from the query log. |
| `get_merge_status` | Running merge operations with progress. |
| `explore_table_schema` | Schema exploration: list databases, summarize tables, or full schema with relationship discovery. |

All tools are read-only and respect the `CLICKHOUSE_MAX_EXECUTION_TIME` limit configured on the server.

Pass `hostId` (integer, default `0`) to any tool to target a specific host when `CLICKHOUSE_HOST` lists more than one.

---

## Example prompts

Paste any of these into Claude, Cursor, or your MCP client after connecting:

**Schema and discovery**

- "List all databases and show me their sizes."
- "Show me the schema of the events table in the analytics database."
- "Find all tables with more than 1 billion rows."

**Performance and queries**

- "Show me the slowest queries from the last hour."
- "Are there any queries running for more than 60 seconds right now?"
- "What queries are consuming the most memory?"

**Replication and merges**

- "Why is replication lagging? Check the replication queue."
- "Are there any merge operations stuck or taking too long?"
- "Which tables have the most parts right now?"

**System health**

- "What is the current memory usage of the ClickHouse server?"
- "How many active connections are there and what is the server uptime?"

---

See [MCP Server](/reference/mcp-server) for the full security model, resource URIs, and pre-built prompts.