MCP server

The chmonitor MCP server at /api/mcp — endpoint, available tools, resources, authentication, and security model.

chmonitor exposes a Model Context Protocol (MCP) server at /api/mcp. It lets external AI tools — Claude, Cursor, and any MCP-compatible client — query your ClickHouse clusters through the same read-only access the dashboard uses.

Endpoint

Property	Value
URL	`https://your-deployment.example.com/api/mcp`
Transport	Streamable HTTP (`POST` / `GET` / `DELETE`)
Session	Stateless — no session id required
Access	Read-only ClickHouse queries

The server identifies itself as clickhouse-monitor. Pass hostId (default 0) to target a specific host from CLICKHOUSE_HOST.

Setup

Connect a client, then verify the connection.

Add the server to your client

One command:

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

Omit --header for a local unauthenticated instance.

Add to your MCP client config file:

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

Omit headers only for a local unauthenticated instance (see Security below).

Settings → MCP → Add Server → paste the endpoint URL. Add an Authorization: Bearer chm_... header if auth is enabled.

Test the connection

curl -X POST https://your-deployment.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.

For step-by-step client walkthroughs (including Claude Code and any generic MCP client), see MCP Client Setup.

Authentication

Production deployments should protect the MCP endpoint. Two methods are supported; either one authenticates a request.

Recommended for scripts and MCP clients.

Set CHM_API_KEY_SECRET and issue chm_ tokens at POST /api/v1/auth/api-key. Send as Authorization: Bearer chm_.... Tokens are HMAC-SHA-256 and time-limited.

See API Keys for setup.

For browser-based MCP clients.

When CHM_AUTH_PROVIDER=clerk is set, /api/mcp also accepts Clerk OAuth bearer tokens. The client completes a standard OAuth browser flow; chmonitor acts as the resource server and verifies tokens via Clerk REST introspection using CLERK_SECRET_KEY.

See Authentication for provider setup.

Available tools

The MCP server exposes 11 read-only tools — a focused subset of the dashboard agent's capabilities. See AI Agent — Capabilities for how these map to the broader agent toolset.

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 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 with relationship discovery.
`analyze_performance`	Combined health report: slow queries, parts, merges, memory, disk.
`get_optimization_recommendations`	Ranked query-optimization advice — skip-index, projection, partition key, or PREWHERE rewrite — with rationale and estimated savings.

All tools are read-only and respect the same CLICKHOUSE_MAX_EXECUTION_TIME timeout as the dashboard.

Resources and prompts

The server exposes static and templated resources for context loading:

Resource	URI	Host-scoped equivalent
System tables reference	`clickhouse://system-tables`	—
Query examples	`clickhouse://query-examples`	—
Database list	`clickhouse://databases`	`clickhouse://hosts/{hostId}/databases`
Tables in a database	`clickhouse://databases/{database}/tables`	`clickhouse://hosts/{hostId}/databases/{database}/tables`
Table schema	`clickhouse://databases/{database}/tables/{table}/schema`	`clickhouse://hosts/{hostId}/databases/{database}/tables/{table}/schema`
Table parts	`clickhouse://databases/{database}/tables/{table}/parts`	`clickhouse://hosts/{hostId}/databases/{database}/tables/{table}/parts`

On a multi-host deployment (comma-separated CLICKHOUSE_HOST), the plain clickhouse://databases/... resources always query host 0, same as omitting hostId on a tool call. Use the clickhouse://hosts/{hostId}/... variant to target another host.

Pre-built prompts for common workflows: health-check, slow-query-analysis, storage-audit, replication-check, capacity-report.

Security

Read-only. All tools run read-only queries. The server never mutates data.
Auth is opt-in. The endpoint requires a token only once an auth scheme is configured. It accepts a chm_ API key (CHM_API_KEY_SECRET) or a Clerk OAuth bearer token (CHM_AUTH_PROVIDER=clerk). Either scheme alone is sufficient; they can coexist on the same endpoint. When a scheme is configured, a missing or invalid token is rejected with 401.
Open when nothing is configured. If neither CHM_API_KEY_SECRET nor Clerk is configured, the endpoint serves anonymous requests — regardless of NODE_ENV. This is the self-hosted default; close it by configuring either scheme. Keep an unconfigured endpoint on a trusted network.
Shared credentials. Queries use the dashboard's configured ClickHouse user. Visibility is bounded by that user's grants.

Secure the MCP endpoint in production

Do not expose the MCP endpoint publicly without setting CHM_API_KEY_SECRET. Anyone with access can read all data the ClickHouse user can see.

See Environment Variables for CHM_API_KEY_SECRET and auth variables. See Features — MCP for more on the MCP feature and how to gate it.

MCP server

Endpoint

Setup

Add the server to your client

Test the connection

Authentication

Available tools

Resources and prompts

Security

MCP client setup

AI Agent — Capabilities

API keys

Features — MCP

On this page