Skip to content

mcp-clients.mdx

Latest commit

 

History

History
195 lines (137 loc) · 5.97 KB

mcp-clients.mdx

File metadata and controls

195 lines (137 loc) · 5.97 KB
Raw
description Connect Claude Desktop, Cursor, Claude Code, or any MCP-compatible client to your chmonitor deployment.
icon PlugZap
title MCP client setup

Connect Claude Desktop, Cursor, Claude Code, or any MCP-compatible client to your chmonitor deployment, step by step. The server-side reference (endpoint, tools, security model) is at 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 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

Run this once, on the server:

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.

Client setup

<Tabs items={['Claude Desktop', 'Claude Code', 'Cursor', 'Any MCP Client']}>

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:

{
  "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.

Run the one-liner in your terminal:

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

For authenticated deployments, add the header:

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:

claude mcp list

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):

{
  "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).

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

Verify connectivity before configuring your client:

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?"

Related