MCP Server

Open as Markdown

Expose your chmonitor instance as a Model Context Protocol server so AI assistants can query your ClickHouse cluster directly.


Routes	`/mcp` (UI info page)
Feature id	`mcp`
Default access	Closed (401) — requires `CHM_API_KEY_SECRET`, `CLERK_SECRET_KEY`, or `CHM_MCP_PUBLIC=true`
System tables	None directly — the MCP server wraps the same tools available to the rest of the dashboard
ClickHouse grants	Inherits grants of the configured `CLICKHOUSE_USER`

What it does

chmonitor exposes a remote MCP (Model Context Protocol) endpoint at /api/mcp. External AI tools — Claude Desktop, Cursor, or any MCP-compatible client — can connect and run tools against your ClickHouse cluster without direct database access.

The MCP server is stateless and uses Streamable HTTP transport. Each request is independently authenticated.

Tools available via MCP include schema exploration, query execution, metrics, health checks, and more. The /mcp page in the dashboard UI shows the connection URL and instructions for configuring an MCP client.

See MCP Server reference for the full tool list and protocol details.

Pages

Page	Route	What it shows	System tables
MCP Info	`/mcp`	Connection URL, setup instructions, tool list	—

Permissions & access

The MCP endpoint (/api/mcp) is closed by default. Anonymous requests receive a 401 response unless at least one of the following is true:

CHM_API_KEY_SECRET is set (API key auth — recommended for production)
CLERK_SECRET_KEY is set (Clerk OAuth)
CHM_MCP_PUBLIC=true is set (explicit opt-in for trusted private networks; a warning is logged on every request)

Production setup — API key auth:

CHM_API_KEY_SECRET=<random-secret-min-32-chars>

Issue a token:

curl -X POST https://your-chmonitor.example.com/api/v1/auth/api-key \
  -H "Authorization: Bearer $CHM_API_KEY_SECRET"
## returns {"token":"chm_..."}

Pass the token in MCP client requests:

Authorization: Bearer chm_...

Production setup — Clerk OAuth (MCP OAuth flow):

When CHM_AUTH_PROVIDER=clerk, the /api/mcp endpoint also accepts Clerk OAuth bearer tokens. Clerk acts as the auth server; chmonitor verifies the token via REST introspection using CLERK_SECRET_KEY. No additional MCP-specific configuration needed.

Disable the MCP feature (removes it from the nav and blocks /api/mcp):

CHM_FEATURE_MCP_ENABLED=false

Config file:

[features.mcp]
enabled = true

Configuration

Variable	Description
`CHM_API_KEY_SECRET`	Enables API key authentication for all `/api/v1/*` routes including `/api/mcp`. Required for production use without Clerk.
`CLERK_SECRET_KEY`	Enables Clerk OAuth token verification. Used for Clerk OAuth token introspection.
`CHM_MCP_PUBLIC`	Set to `true` to allow anonymous access when no auth scheme is configured. Only appropriate for trusted private networks. A warning is logged on every request when this is active.
`CHM_AUTH_PROVIDER`	`none` (default), `clerk`, or `proxy`. Controls how sessions are verified.

The MCP endpoint is secure by default: it returns 401 when no auth is configured, unless CHM_MCP_PUBLIC=true is explicitly set.

Notes & limitations

The MCP server is stateless. It does not maintain session state between requests.
All queries executed via MCP run as the ClickHouse user configured in CLICKHOUSE_USER. Grant that user only the permissions it needs.
Tool availability via MCP mirrors the dashboard’s query capabilities. MCP does not expose write operations by default; control tools (AGENT_ENABLE_CONTROL_TOOLS=true) would be needed for kill/optimize actions, and even then those are not exposed via MCP.
The /mcp UI page is purely informational. The protocol endpoint is /api/mcp.