How to Configure Windsurf ClickHouse MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up a windsurf clickhouse mcp server, register the server in your agent setup file. Then link it to a database user with strict read permissions. Teams often rush this step and use an admin account for speed. Broad roles let an AI agent read private tables or run heavy queries by mistake. A safe setup pairs local agent rules with strict database user roles. How a windsurf clickhouse mcp server works Cognition renamed Windsurf to Devin Desktop in June 2026. The app keeps the same IDE fea

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.

To set up a windsurf clickhouse mcp server, register the server in your agent setup file. Then link it to a database user with strict read permissions. Teams often rush this step and use an admin account for speed. Broad roles let an AI agent read private tables or run heavy queries by mistake. A safe setup pairs local agent rules with strict database user roles.

How a windsurf clickhouse mcp server works

Cognition renamed Windsurf to Devin Desktop in June 2026. The app keeps the same IDE features and the Cascade agent. The Cascade agent connects to MCP servers listed in your local setup file. It can also run terminal commands with your approval in a dedicated shell. This shell loads your local profile, so shell variables and aliases stay active.

When the agent needs data, it sends a request to the MCP server. The MCP server turns that request into a SQL query for ClickHouse. ClickHouse then checks the database user linked to that server session. You can manage ClickHouse users, roles, row rules, and quotas with SQL commands. Turning on SQL access control takes a set storage path on the server. It also needs at least one user with user management rights enabled.

When you create a user for the agent, you set its login method. You can also limit which hosts that user can connect from. You can assign default roles and custom settings to that user account too. In ClickHouse, a user can only grant rights that they already hold.

Setting up column grants for the agent

A good setup limits which tables and columns the agent can read. ClickHouse lets you grant read rights on single columns in a table. If a user only has rights on two columns, queries on others fail. Running a select-all query on that table will also fail and return nothing. A select-all query only works if the table holds just the allowed columns. Since version 24.10, you can also grant rights by table name prefix. An asterisk at the end of a name covers all matching tables.

Teams often create a dedicated role just for their AI coding tools. They attach column grants and row rules to this role. Then they assign the role as the default for the MCP server user. This stops the agent from reading secret tables that sit in the same database.

ClickHouse Access Management + Kubernetes API Server Access: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native setup solves and what keeps the session active

Native database roles and local MCP setup files solve basic login control. They decide which user logs in and which tables that user can see. Host limits also stop outside machines from using the agent login details. Column grants block the agent from pulling columns that you did not approve.

Yet this native setup leaves a big gap during live agent runs. Once the agent logs in, the database trusts every allowed query it sends. Static grants cannot check the text inside an allowed column before returning results. If an allowed column holds emails, phone numbers, card numbers, or national IDs, raw values return. Data masking is needed to rewrite matched fields in results before the agent reads them. Also, local setup files often store database keys in plain text on laptops. Since the agent shell loads user profiles, terminal commands might read those local keys. Finally, database roles do not require human sign-off for a risky query in flight.

Check ClickHouse queries and results before execution

Access control in ClickHouse is essential setup. Setup alone does not check single queries for risk or rewrite sensitive strings in returned rows. By design, hoop.dev sits inline in the protocol beside the server as a sidecar for your ClickHouse. On every query an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.

First, hoop.dev guardrails block disallowed deletes, drops, and alter mutations or hold them for review. Then hoop.dev data masking rewrites sensitive string columns in responses in memory and logs each decision per resource. Read the docs and source on GitHub.

Frequently asked questions

Did Windsurf change its name to Devin Desktop?

Yes, Cognition renamed Windsurf to Devin Desktop in June 2026. The app keeps the same IDE features, and the Cascade agent still uses MCP servers.

Why does a select-all query fail on a restricted ClickHouse table?

ClickHouse blocks select-all queries when a user only has grants on specific columns. The query only works if the user has rights on every column in that table by default.

Where should I store database keys for local MCP servers?

Avoid keeping long-lived database keys in plain text files on developer laptops. Remember that the agent shell loads local profiles and can read exported shell variables.

The query runs. The emails stay hidden.