MCP Server

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.

---

Connect an MCP client

Claude Desktop

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

Cursor

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}'

---

Authentication

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

API keys (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.

Clerk OAuth (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 the same read-only capabilities as the dashboard agent. For a full list of tools, see AI Agent — Capabilities.

Quick summary of core 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 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.

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
System tables reference	clickhouse://system-tables
Query examples	clickhouse://query-examples
Database list	clickhouse://databases
Tables in a database	clickhouse://databases/{database}/tables
Table schema	clickhouse://databases/{database}/tables/{table}/schema
Table parts	clickhouse://databases/{database}/tables/{table}/parts

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.

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.