chmonitorMCP Server
Expose your chmonitor instance as a Model Context Protocol server so AI assistants like Claude and Cursor can query ClickHouse directly.
Turn your chmonitor instance into a remote Model Context Protocol server so AI assistants — Claude Desktop, Cursor, or any MCP client — can run tools against your ClickHouse cluster without direct database access.
Prop
Type
Quickstart
One-command install for Claude Code:
claude mcp add --transport http clickhouse-monitor https://your-chmonitor.example.com/api/mcp \
--header "Authorization: Bearer chm_your_api_key"Omit --header for an unauthenticated local instance. For Claude Desktop, Cursor, and
any other MCP client, see MCP Client Setup.
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 the 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 | — |
Using it
Pick an auth scheme, then point your MCP client at /api/mcp.
Set a secret to enable API key auth for all /api/v1/* routes including /api/mcp:
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"Pass the token in MCP client requests:
Authorization: Bearer chm_...When CHM_AUTH_PROVIDER=clerk, the /api/mcp endpoint also accepts Clerk OAuth bearer tokens (the MCP OAuth flow). Clerk acts as the auth server; chmonitor verifies the token via REST introspection using CLERK_SECRET_KEY. No additional MCP-specific configuration is needed.
Allow anonymous access when no auth scheme is configured. Only appropriate for trusted private networks — a warning is logged on every request:
CHM_MCP_PUBLIC=truePermissions & access
Secure by default
The MCP endpoint (/api/mcp) returns 401 Unauthorized by default. It only opens when you explicitly configure at least one of:
CHM_API_KEY_SECRET— API key auth (recommended). See API keys.CLERK_SECRET_KEY— Clerk OAuth token introspection. See Clerk authentication.CHM_MCP_PUBLIC=true— explicit opt-in for trusted private networks. A warning is logged on every request.
Without one of these, every request — including from Claude Desktop, Cursor, and other MCP clients — is rejected with 401.
Disable the MCP feature (removes it from the nav and blocks /api/mcp):
CHM_FEATURE_MCP_ENABLED=false# CHM_CONFIG_FILE (TOML)
[features.mcp]
enabled = trueConfiguration
Prop
Type
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
/mcpUI page is purely informational. The protocol endpoint is/api/mcp.
Related
Dashboard
Build and save a custom monitoring view by combining any built-in charts on one canvas, stored in the browser.
Inbound Events
Ingest Alertmanager, Datadog, and generic webhook events into chmonitor — normalized, de-duplicated, retained ~30 days, and optionally re-emitted to your outbound alert routes.