chmonitor

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 idmcp
Default accesspublic
Requires authAPI key or Clerk OAuth required in production (see below)
System tablesNone directly — the MCP server wraps the same tools available to the rest of the dashboard
ClickHouse grantsInherits 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

PageRouteWhat it showsSystem tables
MCP Info/mcpConnection URL, setup instructions, tool list—

Permissions & access

The MCP endpoint (/api/mcp) follows the same auth model as the rest of the API. By default (CHM_AUTH_PROVIDER=none, no CHM_API_KEY_SECRET), it is open. This is only appropriate for trusted private networks.

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

VariableDescription
CHM_API_KEY_SECRETEnables API key authentication for all /api/v1/* routes including /api/mcp. Required for production use without Clerk.
CHM_AUTH_PROVIDERnone (default), clerk, or proxy. Controls how sessions are verified.
CLERK_SECRET_KEYRequired when CHM_AUTH_PROVIDER=clerk. Used for Clerk OAuth token introspection.

The MCP endpoint does not have its own separate auth layer — it reuses the global auth configuration.

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.