ClickHouse MCP: An Honest Look at the 3-Tool Limit

A ClickHouse MCP server lets an AI client query your ClickHouse in plain English. Every option available today is read-only, and how much it can see depends entirely on where your database runs: three tools if you self-host or use a third-party managed provider, thirteen if you are on ClickHouse Cloud. None of them can change anything.

If you are wiring Claude Code, Cursor, or VS Code to a ClickHouse instance you are responsible for, that split matters more than the setup instructions do. By the end of this article you will know which server you actually get, how to scope the credentials it runs on, and what an agent’s queries do to your bill.

Worth saying where we stand. Selfhost.dev runs managed ClickHouse, and our own MCP server takes the opposite approach to every server described below: it never connects to your database at all. It runs the infrastructure around it, which turns out to be the half of this problem nobody else’s server touches.

Further down, why that means an agent can provision a ClickHouse cluster, scale it, scope its users, and alert on it, while every ClickHouse MCP server on the market stays read-only.

What a ClickHouse MCP server actually does

It sits between your AI client and ClickHouse, turning natural-language questions into read-only SQL and handing back structured results. In practice that is three capabilities:

• Read-only query execution. It runs SELECT statements. Writes, DDL, and anything destructive are blocked by design.
• Database and table listing. It enumerates what exists, so the model is not guessing at names.
• Schema exposure. Table listings carry column definitions and types, which is what lets the model write SQL that parses on the first attempt.

Any MCP-compatible client can drive it: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, and LibreChat. The open-source server also works against chDB, not only a full ClickHouse instance.

That is the query half of the picture, and it is the only half any ClickHouse MCP server occupies. Every ClickHouse figure below comes from ClickHouse’s own documentation.

The schema piece matters more on ClickHouse than it does on Postgres. There, a query that ignores your indexes is slow. Here, a query that ignores your sorting key is expensive. Filter on a column that sits outside the ORDER BY or PARTITION BY clause and the engine has no way to skip granules, so it reads far more data than the question needed.

A model that cannot see how a table is sorted and partitioned will write exactly that query, confidently. Schema discovery is not a convenience feature here. It is the difference between a cheap answer and one you pay for.

The 3-tool limit: what you get if you self-host ClickHouse

You get three: run_select_query, list_databases, and list_tables. That is the complete tool set for any ClickHouse instance that is not a ClickHouse Cloud service, whether you run it yourself on EC2 or pay someone else to run it for you.

Key takeaway

The open-source ClickHouse MCP server exposes 3 tools. ClickHouse Cloud’s remote server exposes 13, and only for ClickHouse Cloud services. Neither can operate the database.

Each does what its name says. run_select_query runs a read-only SELECT, list_databases returns what is available on the connection, and list_tables lists tables with their column definitions, which is where the model’s schema awareness comes from. There is no fourth tool, no write path, and nothing that touches the server underneath.

ClickHouse publishes the comparison itself:

The open-source server is the portable one and the capped one. It will connect to anything that speaks the ClickHouse protocol, and it will expose exactly three tools when it gets there. If your database sits on a third-party managed ClickHouse instance, the same ceiling applies to you as it does to someone running ClickHouse on a bare VM.

This is not a generous reading of the docs. Tailscale’s guide to connecting Claude Code to ClickHouse puts it the same way: “The ClickHouse MCP server exposes a small set of tools over the Model Context Protocol. It can execute a SELECT query, list databases, list tables, and describe a table schema.” Describing a schema is what list_tables returns rather than a tool of its own, so their four capabilities are the same three tools.

Three tools is also not a bug. For one analyst asking questions of one database, running a SELECT and reading a schema is most of the job. The ceiling only starts to matter when the access stops being personal.

Connecting it to Claude Code, Cursor, or VS Code

The config takes the same shape in every client: a command, its arguments, and the connection details as environment variables.

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "your-host",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-password"
      }
    }
  }
}

Run it with uvx as above, or pull the official image from Docker Hub if you would rather not put Python on the path. Client-specific variations, including the ClickHouse Cloud OAuth flow, are covered in ClickHouse’s own MCP setup guides.

Why 13 tools is a ClickHouse Cloud feature, not a ClickHouse feature

The thirteen-tool remote server works only with ClickHouse Cloud services. The extra ten tools are not a ClickHouse capability you can install somewhere else. They are something you get for being a ClickHouse Cloud customer.

The breakdown, from ClickHouse’s documentation:

• Query and schema (3): run_select_query, list_databases, list_tables
• Organizations (2): List accessible organisations, and fetch details for one
• Services (2): List services in an organisation, and fetch details for one
• Backups (3): List a service’s backups, inspect one, and read the backup schedule and retention settings
• ClickPipes (2): List configured ingestion pipes, and inspect one
• Billing (1): get_organization_cost, returning a grand total plus daily per-entity cost records across a window of up to 31 days

Access runs over streamable HTTP with OAuth 2.0, scoped to the organisations and services the authenticated user can already see. If you are on ClickHouse Cloud, that is the server to point your editor at.

What it is not is portable. Ten of those thirteen tools describe ClickHouse Cloud’s own control plane, so they cannot exist for an instance that has no ClickHouse Cloud behind it, and they stop existing for you the day you move.

Key takeaway

Your MCP capability was set when you chose where ClickHouse runs, not when you chose an MCP server.

Worth knowing what else is tied to ClickHouse Cloud before you build a workflow on it, which is what our Selfhost.dev vs ClickHouse Cloud comparison lays out.

Selfhost.dev takes the opposite approach: Our MCP server manages the infrastructure rather than querying the data, which is why it travels with you and why it can change things. Tinybird’s review of ClickHouse MCP servers reaches the same underlying conclusion from the other direction, that “the choice of MCP server mostly boils down to the choice of self-hosted or managed ClickHouse.”

What no ClickHouse MCP server can do

None of them can operate the database, and that is exactly the gap Selfhost.dev’s MCP server was built to fill. ClickHouse’s documentation is explicit about the constraint: every tool on the remote server is annotated readOnlyHint: true, and “no tool can modify data, alter service configuration, or perform any destructive operation.” An agent can list your backups and read your bill. It cannot create a backup, resize an instance, set an alert, or rotate a credential.

That produces a split worth naming, because none of the marketing makes it obvious:

Every ClickHouse MCP server we looked at sits in the left column. The differences between them are real, but they are differences in how well they read: row-level access scoping, server-side SQL generation, transport options. None of them cross into the right column.

Ours sits entirely in the right column, and the boundary is deliberate. The Selfhost.dev MCP server never connects to your databases at all. It talks to our API, which means no agent driving it can read a row of your data even if it tries, and that removes a whole class of risk before you start.

What it does instead is the work ClickHouse makes tedious: the operate-side tool set provisions instances with their Keeper quorum, adds replicas, forks a cluster for testing, steps a ClickHouse version up in place, scopes database users, and sets alerts on the clickhouse.database metric set.

It will do all of that inside your own AWS account too, if you would rather keep the infrastructure on your side of the bill. That setup is BYOC, and it works the same way through the MCP server.

In practice it reads like this:

Under one of those requests, the agent is calling a sequence of tools rather than one black-box action, and it shows you each step:

> Spin up a ClickHouse cluster for analytics with 2 replicas,
  add a read-only reporting user, and alert me if CPU passes 80%

estimate_instance_cost
✓ 3 nodes · Keeper quorum embedded · itemised monthly estimate returned

create_instance
✓ analytics-ch · ClickHouse 24.8 · 2 replicas · provisioning

create_database_user
✓ reporting · read_only · connection limit 10 · secret shown once

create_alert_rule
✓ create_alert_rule set: CPU > 80% on clickhouse.database → email channel

✓ Cluster running. Nothing destructive was requested, so nothing asked for confirmation.

Scratch that last result line, I duplicated the tool name. Use this one instead:

create_alert_rule
✓ CPU > 80% on clickhouse.database → email channel

The cost estimate arriving before the instance exists is the part worth noticing. You approve a number, then the cluster gets built.

What this looks like on a normal week

Your analytics cluster has been sitting at 80% CPU since Monday.

“CPU on analytics-ch has been pegged all week. Put a scaling policy on it so it resizes itself if it breaches 80% again.”

create_scaling_policy writes a reactive rule against the metric. The next breach handles itself.

A contractor needs read access to one table until Friday.

“Create a read-only user for the contractor, connection limit 5, password expires Friday.”

create_database_user issues it with the expiry attached. Nobody has to remember to revoke it, because it stops working on its own.

Your credit balance is dropping faster than last month.

“What’s my burn rate, and what changed?”

get_wallet_balance returns the hourly rate and the days of runway it leaves. list_wallet_transactions breaks it down per resource, per hour.

None of these are ten-minute jobs in a console. They are thirty-second jobs in a sentence, which is the actual difference an operate-side server makes.

The two halves stack, and that is the part worth being concrete about.

The open-source query server works against any ClickHouse instance, including ours, so on a Selfhost.dev instance you run those three query tools and a second server that can act on the infrastructure.

Ours carries 161 tools across 25 modules for the platform as a whole, and the ones that reach a ClickHouse instance cover its full lifecycle, backups and snapshots, replicas, scaling, database users, alerts, and query pooling. On ClickHouse Cloud you get thirteen tools that can only look, and nothing to add beside them.

Why not just use clickhouse-client?

For one person on their own laptop, the CLI is fine. The skeptics have a real argument, and it goes roughly like this: clickhouse-client already exists, an agent that can run shell commands can already use it, a wrapper burns context tokens describing tools the model could have called directly, and every component you add is a component you maintain.

The credentials problem.

Handing an agent a shell hands it whatever your shell can already reach, with your grants. A scoped MCP connection is a specific database user, read-only, with a connection limit and an expiry date, the kind create_database_user produces on a Selfhost.dev instance. A shell session has none of those properties and cannot be revoked without revoking you.

The audit problem.

With a dedicated identity you can say which queries the agent ran and cut it off without touching anyone else. With a shared shell, it is your name on every row of the query log.

The honest cost of the MCP route is a component with its own attack surface, and there is a specific example rather than a general warning. Datadog Security Labs found a SQL injection flaw in Anthropic’s reference Postgres MCP server that let them bypass its read-only restriction and execute arbitrary SQL. Anthropic patched it, then archived that server along with others it judged not ready for production, and the package was deprecated on 10 July 2025. It was still being installed roughly 21,000 times a week after that.

Which is the part worth internalising: read-only is an implementation promise, not a property of the protocol. So the decision is not CLI versus MCP. It is whether this access needs an identity of its own.

• The CLI is enough when: one person, one database, credentials that are already yours, and nothing to audit.
• MCP earns its place when: an agent runs unattended, more than one person or service shares the connection, or you need to scope, expire, and revoke the access separately from your own.

How to give an AI agent safe access to your ClickHouse

Create a dedicated read-only database user for the agent, give it a connection limit and a password expiry, and never hand it the admin credentials. Everything below is a refinement of that one rule.

• Dedicated user, not shared. One identity per agent, so revoking it costs nothing else.
• Read-only role. The agent’s job is to answer questions, not to alter tables.
• Connection limit. A ceiling on concurrent connections for that user specifically.
• Password expiry. A date the credential stops working whether anyone remembers it or not.
• Rotate on exposure. Any time the config file is shared, committed, or synced somewhere it should not be.
• Store the secret properly. It is shown once. Treat the copy in your client config as the risk, not the copy in your password manager.

The fifth point carries more weight than it looks like it should.

MCP credentials live in a plaintext client config on a developer laptop, beside every other MCP server’s credentials, in a file that gets screenshotted into bug reports and synced between machines. Treat it as exposed by design and rotate on a schedule, rather than treating it as a secret and hoping.

Selfhost.dev treats database users as first-class on PostgreSQL, MySQL, and ClickHouse. create_database_user takes a read_only, read_write, or admin role plus a connection limit and a password expiry. rotate_database_user_password issues a new secret and shows it once.

You can build exactly that user yourself in the interactive console demo, no signup needed. If you run Postgres alongside ClickHouse, the same pattern holds there, and PostgreSQL MCP Server: A Complete Guide to AI-Driven Database Management walks through it engine by engine.

The other end of the connection matters too. Ours stores credentials at ~/.selfhost/credentials.json with owner-only permissions, strips passwords, keys, and tokens out of API responses, and requires explicit confirmation before any destructive operation runs.

That last mechanic is the one worth comparing directly, given what the Datadog case study showed. ClickHouse’s answer to agent safety is to make every tool read-only, which is genuinely safer and is also the reason nothing can be automated.

Confirmation gating reaches the same place from the other direction: the agent can act, but it stops and asks before anything is deleted, stopped, or rebooted.

Stopping a runaway agent from saturating your connections

An agent in a retry loop opens connections faster than a person does, and ClickHouse concurrency is finite. Two mechanics contain it. The per-user connection limit above caps that identity specifically, so a stuck agent cannot starve your application. Query pooling handles the rest: CHProxy fronts ClickHouse over HTTP on port 9090 with concurrency and queue limits, leaving the native TCP interface on 9000 untouched.

Rate limiting is the backstop on the control-plane side. Our API caps roughly 300 reads and 120 writes per minute per account, which bounds how fast an agent can issue management calls even if its logic has gone wrong.

What an AI agent actually costs you on ClickHouse

The cost is not the tokens, it is the meter. An agent exploring your data writes queries whose scan volume you cannot predict in advance, and on usage-based ClickHouse pricing an unpredictable scan is an unpredictable bill.

An analyst who knows the table filters on the partition column out of habit. An agent asked an open question optimises for answering it, not for touching less data, so it will happily write the version that reads everything, return the right answer, and move on.

ClickHouse appears to agree this is real, and their engineering choices are the tell. The remote MCP server ships a billing tool, get_organization_cost, returning a grand total plus daily per-entity cost records. An analytics vendor decided that agents connected to their database need visibility into spend. Worth asking why that was necessary, and worth noticing that it lets an agent watch a meter it has no power to stop.

• What drives the cost: unpredictable scan volume from queries nobody wrote by hand.
• What monitoring gives you: the number, after it happened.
• What removes the variance: a flat hourly instance, where scan volume stops being a billing event.

That is the structural difference, and it is worth being precise about its edges. On a dedicated instance billed by the hour, compute is fixed: a hundred badly shaped queries cost the same in compute as none. Storage and egress still scale, so a query that ships a large result set out of the region is not free anywhere. What disappears is the compute meter, and that is the line that moves when an agent explores.

Selfhost.dev bills that way against prepaid credits that stop at a zero balance, so nothing accrues in hindsight. get_wallet_balance returns your current burn rate and runway, and estimate_instance_cost itemises the bill before an instance exists rather than after.

The concept has a name and a fuller treatment in our guide to bill variance, and for the ClickHouse Cloud side, our breakdown of what ClickHouse actually costs at 24/7 has the arithmetic.

One honest caveat: if your agent usage is genuinely occasional, a few questions a week from one analyst, this is a rounding error and predictability is not the reason to move anything. The argument matters when agent access becomes routine, or when it gets embedded in a product.

If you want the number before you commit to anything, build your exact bill on the pricing calculator. No signup. If agent queries have already moved your invoice and you want someone to look at where it went, the free cost audit is the faster route.

Which ClickHouse MCP setup fits your stack

Three scenarios, three different answers. On ClickHouse Cloud and staying there, use their remote server. Self-hosted or on a third-party provider, the open-source server’s three tools are your querying ceiling. Wanting an agent that operates the infrastructure rather than reads from it is a second server and a separate decision.

Nothing in that table is either-or. Querying and operating are different jobs, and running one server for each is the normal end state rather than a compromise.

If the question is why point an agent at a Selfhost.dev instance specifically, it comes down to three things. It is the only row in that table where an agent can change anything, so provisioning a Keeper quorum or scoping a reporting user becomes a sentence rather than a ticket. You keep the query side, because the open-source server works against our instances exactly as it works anywhere. And the spending is bounded by design: everything runs against prepaid credits that stop at a zero balance, with cost itemised before an instance exists, so an agent with a bug cannot hand you an invoice you did not expect.

One thing to know either way: snapshots are the recovery path for ClickHouse everywhere, ours included, because ClickHouse recovers from snapshots rather than replaying a write-ahead log.

So the decision in front of you is not which MCP server to install. It is where your database runs, because that is what set your ceiling before you opened your editor. If that is the decision you are actually making, the managed ClickHouse options are worth comparing on more than their MCP support.

If you would rather see it than read about it, the interactive console demo runs a full MCP-driven flow end to end, and you can spin up managed ClickHouse inside it yourself. No signup, no card.

Managed ClickHouse starts at $27/month for a single node in Mumbai, and the pricing calculator itemises any other config before you commit to it. When you want a real instance, start free in the console, no card needed.

Frequently Asked Questions