How to Configure Claude Code ClickHouse MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a claude code clickhouse mcp server by adding the server to your agent. Next, you give it a read-only database user so queries cannot change data. Teams often rush this setup and reuse broad admin roles from local apps. Broad roles let the AI agent read sensitive tables or drop production data by mistake. How the claude code clickhouse mcp server setup works Claude Code talks to outside systems and databases through the Model Context Protocol. This protocol lets the AI agent run qu

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up a claude code clickhouse mcp server by adding the server to your agent. Next, you give it a read-only database user so queries cannot change data. Teams often rush this setup and reuse broad admin roles from local apps. Broad roles let the AI agent read sensitive tables or drop production data by mistake.

How the claude code clickhouse mcp server setup works

Claude Code talks to outside systems and databases through the Model Context Protocol. This protocol lets the AI agent run queries against your analytical tables. The vendor docs tell users to verify they trust each server before connecting. The docs also advise using a read-only database user in the connection string. That way, the queries the agent runs cannot modify your stored data. You also need to watch the built-in Bash tool in the agent. In manual mode, the Bash tool asks for approval before running shell commands. Still, it runs a built-in list of read-only commands without asking first.

On the database side, ClickHouse manages users, roles, and quotas with SQL commands. To turn on SQL access control, you set a storage path on the server. You also enable access management for at least one admin user. That admin can then create a dedicated user for the AI agent. A user can only grant privileges that they already hold themselves. When you create the agent user, you set its login method and allowed hosts. You also assign default roles and specific user settings for that account.

Scoping table and column permissions in ClickHouse

A basic read-only role across the whole cluster is still too broad for agents. Analytical databases often hold customer emails, phone numbers, card numbers, and national IDs. You can tighten access by granting select rights on specific columns only. When you grant select on two columns, the user can query only those columns. If the agent tries to query a third column, the database blocks the query. A select-all query also fails unless the table holds only the allowed columns. Since version 24.10, you can also grant select rights using a table name prefix. A trailing asterisk on the prefix covers all matching tables in that database.

Row policies and quotas add another layer of control Inside the database engine. Row policies filter which rows a given user role can read during a query. Quotas cap how much resource usage a user can consume over a time window. These native features help teams limit what the agent account can reach.

Claude Code Security + ClickHouse Access Management: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native setup solves and what it leaves open

Native database roles and read-only users solve the first layer of access control. They decide who can log in and which tables or columns that account can read. They also stop the AI agent from running delete or update statements on tables. This setup is much safer than sharing a root database password with an agent.

Still, static database roles leave a big operational gap open during live sessions. The database user lives in a local file on the developer machine. Anyone or any script on that machine can read and reuse that credential. Also, column grants are all-or-nothing for the columns you allow the agent to read. If the agent needs a column that holds emails or card numbers, raw values return. Native roles cannot rewrite matched fields in results to mask emails or phone numbers. Finally, static roles check who logs in, not what each query does in flight. Teams lack a central audit log that ties each agent query to a human user. They also cannot pause a risky query for human approval before it hits the database.

Add runtime guardrails and masking beside ClickHouse

Database grants and network rules control who can reach ClickHouse. Even so, an allowed client or agent can send an alter mutation that deletes rows or read raw personal data. In practice, hoop.dev sits inline in the native TCP protocol beside the server as a sidecar for your ClickHouse. For every production query an agent or human sends, hoop.dev decides whether to pass, mask, block, or escalate it for review.

With hoop.dev ClickHouse support, guardrails refuse banned queries before they run or hold risky calls for approval, and data masking rewrites matched string columns in results in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.

Frequently asked questions

Why should I use a read-only user for the Claude Code MCP server?

A read-only user stops the AI agent from changing or deleting your database records. Even if a prompt goes wrong, the database rejects any write or drop statement.

How does ClickHouse handle select-all queries when column grants are active?

ClickHouse refuses a select-all query and returns no data if some columns are restricted. A select-all query only works when the user has rights to every column in that table by default.

Can a ClickHouse user grant permissions to the AI agent that they do not have?

No, ClickHouse rules state that a user can only grant privileges they hold themselves. You must use an account with access management turned on to set up new roles.

The query runs. The emails stay hidden.