ClickHouse MCP: Give Your AI Agent Type-Safe Access to Analytics Data

The Model Context Protocol (MCP) is how AI agents get access to external tools. If you're running ClickHouse and want an AI agent — Claude, Cursor, a custom GPT — to be able to query your analytics data, you need an MCP server that exposes your ClickHouse queries as structured tools.

Most MCP + ClickHouse examples do the same thing: open a database connection and let the model write arbitrary SQL. This works for exploration. It's wrong for production.

The problems with arbitrary SQL over MCP: no tenant isolation (a model that can write any query can read any tenant's data), no type contract (the agent doesn't know what shape to expect back), no access control (every table is reachable), and no audit trail.

This post shows a different approach: use hypequery's serve layer to define your queries first, then expose them as MCP tools. The agent gets access to structured, pre-defined, typed query functions — not a raw SQL interface.

How hypequery serve + MCP fits together

hypequery's @hypequery/serve package takes a set of typed query objects and exposes them as an HTTP API with an OpenAPI spec. That OpenAPI spec is machine-readable — exactly what you need to generate MCP tool definitions.

ClickHouse
    ↓
hypequery query objects (typed, tenant-isolated, auth-checked)
    ↓
@hypequery/serve → HTTP API + OpenAPI spec
    ↓
MCP server (reads OpenAPI, exposes as tools)
    ↓
AI agent (Claude, Cursor, custom)

The agent never touches ClickHouse directly. It calls tool functions that are backed by your pre-defined, type-safe query objects.

Step 1: Define your queries

These are typed query objects. They know their output shape. Tenant isolation is injected via context — the agent can't bypass it because it never sees the WHERE clause.

Step 2: Expose as HTTP API

GET /dailyRevenue and GET /topProducts are now live. hypequery generates an OpenAPI spec at /openapi.json.

Step 3: Generate MCP tools from the OpenAPI spec

The MCP server dynamically reads whatever queries hypequery exposes. Add a new query to serve({ queries }) and it appears as a new tool automatically — no manual MCP registration.

What the agent sees

With this setup, a Claude agent connected to this MCP server sees:

dailyRevenue() — Returns daily revenue totals for the last 30 days
topProducts()  — Returns top 10 products by revenue

It can call these tools and reason over the structured response. It cannot write arbitrary SQL. It cannot read tables you haven't defined queries for. It cannot see data from other tenants.

Adding parameters

hypequery adds the input schema to the OpenAPI spec. The MCP server registers the tool with the correct parameter definitions. The agent can now call revenueByDateRange({ from: "2026-01-01", to: "2026-01-31" }) with type-checked inputs.

Why this matters

The naive "give the agent raw SQL access" approach has a short shelf life in any multi-tenant or production system. Pre-defined query objects give you access control, tenant isolation, predictable response shapes, and auditability.

The hypequery serve layer was designed for this: define queries once, expose them in multiple contexts. MCP is one more context.

Getting started