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 speaks the 2026-07-28 protocol revision over the
Streamable HTTP transport, while still answering pre-2026 clients. Each request is
independently authenticated and carries its own protocol version — there is no
initialize handshake and no session id. Successful tool results include both a
text block and machine-readable structuredContent.
Tools available via MCP include schema exploration, query execution, metrics, health checks, and more.
The /mcp page
The dashboard's /mcp page is the console for this endpoint:
- Setup Guides — per-client instructions (Claude Desktop, Claude Code, Cursor, any other MCP client) with a copy-config button on each row.
- Tools — every tool with its arguments, defaults, and an example response.
- Playground — a real MCP client for your own endpoint: it discovers the live tool list, builds a form from each tool's JSON Schema (with a raw-JSON editor for complex arguments), runs the call, and shows the text + structured result plus a request/response inspector. If the endpoint requires a credential it prompts for an API key instead of failing; plan-gated and rate-limited responses are explained rather than surfaced as raw errors.
- Example Prompts — starting points to try in your assistant.
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.