ClickHouse MCP
Connect AI agents to ClickHouse — without exposing raw SQL
hypequery turns typed ClickHouse query definitions into an MCP-ready HTTP API. Your AI agent calls structured tools, not arbitrary SQL. Tenant isolation and access control are built in at the query level.
Agent access model
Structured tools
Tenant isolation
Query-level
Works with
Claude, Cursor, custom agents
Arbitrary SQL access has no tenant isolation
If the model can write any SQL, it can read any tenant's data. Prompt engineering is not access control. Pre-defined query objects are.
The agent has no predictable response shape
Without pre-defined output types, the agent guesses what structure it gets back. Inconsistent responses break agent reasoning and make outputs unreliable.
You have no audit trail over what ran
Arbitrary SQL execution means you have no record of what queries an agent ran or what data it accessed. Pre-defined tools give you a fixed, auditable surface.
How hypequery + MCP works
Pre-defined queries become MCP tools automatically
Define your queries with hypequery. Expose them via @hypequery/serve — it generates an OpenAPI spec at /openapi.json. Your MCP server reads that spec and registers each query as a tool. The agent calls tools, not SQL.
- Tenant isolation injected at the query level — agents cannot bypass it
- Access control enforced at the serve layer — only exposed queries are reachable
- OpenAPI spec auto-generated — no manual MCP tool registration needed
- Input schemas from Zod definitions become typed tool parameters
- Add a new query to serve({ queries }) — it appears as a new tool automatically
Query definition
Typed queries with tenant isolation built in
The agent never sees the WHERE clause. It just calls the tool. Tenant context is injected from the request headers — enforced at the query level, not in a prompt.
MCP server
Read the OpenAPI spec, register tools automatically
Because hypequery generates a standard OpenAPI spec, the MCP server can discover tools dynamically. No hard-coded tool list. No manual sync between the analytics layer and the agent layer.
The agent sees named tool functions — dailyRevenue(), topProducts() — not a raw database. It gets structured responses with predictable shapes that it can reason over reliably.
Input parameters from Zod schemas flow through to the MCP tool registration. The agent can call parameterised queries with type-checked arguments.
MCP server
Auto-register tools from the OpenAPI spec
This MCP server reads the hypequery OpenAPI spec and registers each endpoint as a tool. Add a query to your analytics layer — it becomes a tool without touching this file.
Why teams search for this
Common implementation questions this page should solve
ClickHouse MCP server
If you want a ClickHouse MCP server, the question is whether to expose raw SQL or pre-defined query tools. For production or multi-tenant systems, pre-defined tools are the right default.
Give Claude access to ClickHouse
Claude can call MCP tools to query analytics data. hypequery makes this safe by defining the query surface explicitly — Claude calls tools, not arbitrary SQL.
MCP TypeScript analytics
The stable pattern for MCP + analytics databases is: define typed queries on the server, expose them via HTTP, generate MCP tools from the OpenAPI spec. hypequery handles the middle layer.
AI agent ClickHouse access control
Access control for AI agents should not live in the prompt. It should live at the query definition level, where it's enforced regardless of what the model asks.
Further reading
Go deeper with comparison posts and implementation guides
ClickHouse MCP: full implementation guide
Step-by-step guide to building a typed MCP server on top of hypequery with tenant isolation.
Open guide
HTTP and OpenAPI docs
How @hypequery/serve exposes queries as HTTP endpoints and generates the OpenAPI spec.
Open guide
The query() API
How hypequery 0.2.0 makes one query definition run in inline, HTTP, and agent contexts.
Open guide
ClickHouse query builder
The typed query builder that backs the analytics layer your MCP server exposes.
Open guide
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.