ClickHouse MCP

Connect AI agents to ClickHouse — without exposing raw SQL

This page is about choosing the tool surface an agent gets. If the model can write arbitrary SQL, your access control story is already weak. hypequery lets you expose a small set of named analytics queries instead.

Open serve docs Read the full guide

Agent access model

Structured tools

Tenant isolation

Query-level

Works with

Claude, Cursor, custom agents

Raw SQL is the wrong primitive for agent access

If the model decides what to query directly, you have already handed over too much surface area. Prompt instructions are not a meaningful replacement for access control.

Agents work better with known result shapes

A named tool returning a predictable payload is much easier to reason over than arbitrary query output that changes shape from call to call.

A fixed tool surface is easier to review and audit

It is far easier to reason about five exposed analytics tools than a general database capability whose behavior depends on whatever the model asks for next.

The safer model

Expose named analytics queries, not a database console

Define a small set of queries with the same typed backend layer you would use for the rest of the app, expose them over HTTP, and register those endpoints as MCP tools. The agent only gets the capabilities you decided to publish.

Tenant isolation injected in the same request path as the rest of your analytics API
Only explicitly exposed queries are reachable by the agent
Input schemas stay next to the query definition instead of inside prompt text
The same backend query layer can serve humans, dashboards, and agents
The tool list stays small enough to review deliberately

Query definition

A served query the agent is allowed to call

the-safer-model.ts

The useful part is that the agent never chooses the SQL. It only calls the query surface you already chose to expose.

MCP server

Register a small tool surface on top of the API

You do not need a magical agent-specific backend. In most cases, a straightforward MCP server that forwards to a few served analytics endpoints is the better design.

That is also easier to audit. The tool list is explicit, the HTTP surface is explicit, and the backend queries are the same ones your application code can already review and test.

If you want to automate tool generation later, the OpenAPI surface makes that possible. The important architectural choice is still the same: expose named queries, not arbitrary SQL.

MCP server

A single MCP tool backed by a served analytics endpoint

mcp-server.ts

Start simple. Register one or two tools against the endpoints you trust, then expand deliberately if the agent use case proves valuable.

Where teams usually get stuck

The questions this page should answer

What this page is really deciding

Not just how to wire MCP to ClickHouse, but what the agent should be allowed to do once it gets there.

What the safer default looks like

A short list of named analytics tools with tenant-scoped backend definitions is much safer than a model deciding which SQL to write.

Why this fits the rest of the stack

The same query layer can already serve dashboards and APIs, so the MCP surface does not need its own separate data-access architecture.

Where to go next

Use the serve/OpenAPI docs for the HTTP layer details and the full MCP guide for the end-to-end wiring pattern.

Next step

Define the queries you want your agent to access

Start with one or two analytics queries. Expose them via @hypequery/serve. Point your MCP server at the OpenAPI spec. Your agent has structured, tenant-safe access to ClickHouse.