AI Toys in the Attic: Our favorite AI tools and techniques for ClickHouse®

Recorded: June 3 @ 09:00 am PDT
Presenters: Robert Hodges, Alexander Zaitsev, and Boris Tyshkevich

In this practical AI webinar, Altinity CEO Robert Hodges and AI architect Boris Tushkovich demonstrate three tools for using LLMs with ClickHouse: the Altinity MCP server, the Altinity Skills project, and OAuth 2.0 guardrails. The session is candid about when LLMs shine — design evaluation and system health assessment — and when they are dangerous: a same-morning customer case where AI may have deleted production data underscores why write access must be blocked.

Robert demos Claude Code with the Altinity MCP server and Grafana MCP running simultaneously, having Claude write a delayed-departures query and build an iterated Grafana dashboard without a single line of handwritten SQL. Boris then loads Altinity Skills — DBA playbooks packaged as SKILL.md files — into the Claude.ai UI and asks Claude to review cluster health, producing HTML reports covering detached parts, system log TTLs, nullable columns, and compression issues.

The safety section shows the Altinity MCP server’s read-only mode blocking all non-SELECT SQL before it reaches ClickHouse. Combined with OAuth 2.0 / OIDC, agents receive JWT tokens automatically mapped to a read-only ClickHouse role via user_directories — natively in Altinity’s Antalya builds, or via the chwt-validator helper on community builds. Boris confirms live: even a user with full database grants cannot execute DDL through the read-only MCP layer.

Key Moments (Timestamps)

Key moments generated with AI assistance.

• 1:06 – Introduction: Robert Hodges, Boris Tushkovich, Alexander Zaitsev
• 2:09 – About Altinity: ClickHouse vendor since 2017, enterprise support, Altinity.Cloud, Kubernetes Operator
• 3:16 – ClickHouse overview: real-time analytic database, 50K GitHub watchers, SQL + columnar + parallel
• 4:21 – Why LLMs + ClickHouse now: models trained on ClickHouse code, fast iteration, design/operations evaluation
• 5:34 – What LLMs do especially well: evaluating designs and assessing system health
• 5:45 – What to avoid: LLMs writing to production data — don’t allow it
• 6:09 – Talk outline: MCP, Skills, authentication/security
• 6:26 – What is MCP? Model Context Protocol: connecting AI brains to external tools and data
• 7:18 – MCP tools, resources, prompts; works across Claude, Codex, Copilot
• 8:04 – Live MCP setup: Claude Code + Altinity MCP + Grafana MCP running simultaneously
• 8:30 – The Altinity MCP server: Go, Apache 2.0, STDIO/SSE/HTTP, execute_query tool, OAuth 2.0
• 9:28 – Registering MCP servers: mcp.json file, automatic startup, altinity-mcp config file
• 10:49 – Demo begins: spinning up Claude Code, checking MCP servers are connected
• 11:35 – Demo: “Build a query showing delayed departures per day from SFO.”
• 12:20 – Demo: Claude queries ClickHouse through MCP, returns a valid query
• 12:43 – Demo: “Create a Grafana dashboard from this query.”
• 13:39 – Demo: Claude queries Grafana MCP, finds Altinity data source, creates dashboard
• 14:15 – Demo: dashboard appears in Grafana with SFO delayed departures panel
• 14:40 – Demo: “add more panels” — Claude adds a pie chart, 0.3s turnaround
• 16:17 – Key learning: use LLMs for planning and prototyping, then reduce to code for production
• 16:50 – Showing MCP servers in Claude.ai web UI: add connectors, enable/disable tools
• 18:08 – Introduction to Skills: packaged playbooks for AI agents
• 18:23 – Skills are not runbooks: they give the LLM pointers to relevant information
• 19:03 – SKILL.md structure: header (always loaded), body SQL files (loaded on demand)
• 19:52 – Context efficiency: only the header loads until the skill is needed
• 20:57 – Altinity Skills project: DBA-focused, any ClickHouse version, open source, Apache 2.0
• 22:00 – Installing skills: npx or git clone + link
• 22:31 – Handoff to Boris Tushkovich for skills demo
• 22:59 – Boris demo: loading skills in Claude.ai UI (connection, schema, overview)
• 24:20 – Boris demo: connecting the Altinity MCP server as a connector in Claude.ai
• 26:09 – Boris demo: “Please review cluster health” — no skill name specified
• 26:35 – Claude autonomously reads connection skill, loads overview skill, runs SQL queries
• 28:40 – Health report: uptime, memory, disk, replication, background pools, DDL queue
• 29:10 – Report finding: detached part that should be deleted (old, quite large)
• 29:17 – Report finding: system log tables without TTL — marked major (common production problem)
• 29:54 – Boris starts second session: “review schema for on-time database”.
• 30:08 – Schema report: MergeTree table, 39 yearly partitions, big dataset
• 30:26 – Schema finding: poor compression on a low-cardinality column
• 30:41 – Schema finding: many nullable columns are not needed
• 31:03 – Schema finding: recommendations for skip indexes
• 31:21 – Robert: skills replace the custom audit script Altinity previously shipped to customers
• 32:26 – Back to slides: guardrails — why not let LLMs carry out the recommendations?
• 33:06 – Data deletion incident: Hacker News story; live customer case that morning (AI may have dropped tables)
• 34:22 – How AI agents gain dangerous access: MCP server + write-enabled accounts + ClickHouse client in PATH
• 35:28 – Solution 1: Altinity MCP read-only mode — SQL parsing layer blocks all non-SELECT commands
• 36:11 – Solution 2: OAuth 2.0 / OIDC for broad read-only access without storing credentials in MCP
• 36:27 – Altinity MCP OAuth flow: broker mode off → Claude authenticates with IDP → receives JWT
• 38:48 – ClickHouse side: Antalya builds have a built-in OAuth token processor; token validated against IDP
• 39:46 – user_directories config: maps OAuth token users to read-only role automatically
• 41:05 – For non-Antalya builds: chwt-validator project validates JWTs via password hook
• 42:09 – Boris demo: OAuth flow in Claude.ai UI; non-Antalya ClickHouse build; CHWT validator in use
• 44:40 – Boris demo: “show my grants” — user has all permissions in ClickHouse
• 45:21 – Boris demo: attempt to create database — BLOCKED by MCP readonly layer
• 46:19 – Boris: MCP as a security layer, not just a data access protocol; future direction for agent safety
• 48:45 – Roadmap: Kubernetes-focused skills
• 49:02 – Roadmap: MCP access baked into Altinity.Cloud (in progress)
• 49:34 – Roadmap: simplifying OAuth documentation and tooling
• 50:05 – Key learning: use lower-cost models (Sonnet) first; escalate to Opus only when needed
• 50:24 – Roadmap: agent optimization — speed, cost, reliability, consistent answers as models change
• 54:03 – Roadmap: local model support — keep sensitive data local, not shipped to hosted LLM providers
• 54:57 – Roadmap: introducing safe agents — log analysis, alerting, automated recommendations
• 55:22 – QR code: Altinity Skills project GitHub repo
• 56:03 – Q&A: MCP for DDL — not in production; fine in dev/staging containers (Boris: great for experiments)
• 58:31 – In-person events: San Francisco, Seattle, Los Angeles (end of June)

Webinar Transcript

[1:06] — Introduction and Housekeeping

Robert: Welcome, everybody, to “AI Toys in the Attic: Our Favorite AI Tools and Techniques for ClickHouse.” My name is Robert Hodges, and I am the CEO of Altinity. I’m joined today by Boris Tushkovich, our AI architect, who combines AI work with support engineering. We also have in the background our CTO, Alexander Zaitsev, who is also with us today.

This talk is being recorded. You’ll get a copy of the slides and the recording by email within a few hours. You can send questions in the chat or the Q&A box — we’ll answer simple ones behind the scenes during the talk.

[2:09] — About Altinity

Robert: If you don’t know us, Altinity is a vendor for ClickHouse. We’ve been in business since 2017 and have hundreds of customers. We offer 24×7 enterprise support, which gives us a huge amount of experience helping customers design and operate ClickHouse applications in practically every environment you can imagine. We also operate a cloud for ClickHouse called Altinity.Cloud – the first cloud for ClickHouse on the hyperscalers – started in 2020. And we’re the authors of the Altinity Kubernetes Operator for ClickHouse, which some of you on this call are probably using today.

[3:16] — What Is ClickHouse?

Robert: The wallet-size description: ClickHouse is a super popular real-time analytic database. For use cases like observability, AI telemetry, SIM evaluations, and market data it is hands-down the favorite for high-speed, cost-performant analytics. The project has almost 50,000 GitHub watchers, gets hundreds of PR contributors per month, and is very widely used. It’s a SQL database with all the good features of MySQL or PostgreSQL combined with all the good features of a modern analytic system: columnar storage, parallel vectorized execution, and so on.

[4:21] — Why LLMs + ClickHouse Now

Robert: Why is this topic so important? Well, obviously everyone’s going a bit crazy about AI — at least our managers and investors are. But there are sound reasons for using LLMs with ClickHouse today.

First, LLMs are astonishingly good at ClickHouse. Because ClickHouse is open source and very popular, models like Claude are trained on ClickHouse code and documentation. They come to the conversation with a huge amount of knowledge.

Second, LLMs enable very fast iteration. They take away the boring work of restructuring SQL, restructuring charts or code, and so on. You can prototype things very quickly.

Third — and this is what we’ll hammer on in this talk — LLMs are great at helping with design and operations, particularly evaluating designs and evaluating the health of current systems. This is where they shine.

What to avoid: using LLMs on production data is still a work in progress, and allowing LLMs to write to production data is not something you want to do. We’ll show you why later.

[6:09] — Talk Outline

Robert: We’ll cover three areas: MCP (Model Context Protocol), Skills, and authentication and security.

[6:26] — What Is MCP?

Robert: MCP is a way of connecting AI applications to external tools and data. Think of an LLM as a brain — but just as we’re not simply brains, we also have hands, feet, ears, and eyes. MCP is a protocol (Model Context Protocol) that allows a model like Claude to connect to and access external services containing interesting data or useful capabilities.

MCP structures communication into three things: prompts, resources (like lists of tables), and — most interestingly — tools, which are API-style endpoints. The great thing about MCP is that practically every major agent framework understands it. If you build an MCP server, it works with Claude, Codex, Copilot, and so on. This is a very powerful unifying protocol.

AI workflows can use many MCP servers simultaneously — one, two, three, or even a couple dozen. The model is very good at figuring out which server to use for what; you don’t have to tell it.

[8:04] — Live Demo Setup: Claude Code + Altinity MCP + Grafana MCP

Robert: Here’s an example of what we’ll be demoing: working with Claude Code at the command line, talking to Claude (Opus 4.8), with two MCP servers active simultaneously — one we wrote that talks to ClickHouse (the Altinity MCP server), and one the Grafana team wrote that talks to Grafana. The model switches transparently between using them.

[8:30] — The Altinity MCP Server

Robert: The Altinity MCP server is a new piece of software we’ve been working on. It’s designed specifically for ClickHouse. It’s written in Go, Apache 2.0 licensed. It supports STDIO, SSE, and HTTP transports. The principal tool it offers is execute_query — a single API call that maps to SQL. It integrates with OAuth 2.0 for authentication, which we’ll discuss in the security section.

To register MCP servers with Claude, you use an mcp.json file that tells Claude how to start each server automatically when you launch it. For the Altinity MCP, a configuration file specifies the transport (STDIO in this case) and the connection details for ClickHouse. In this demo, we’re connecting to a public Altinity demo server, so the credentials are public.

[10:49] — Demo: Building a Grafana Dashboard with Claude

Robert: Let me jump in and show this in action.

I’ll spin up Claude Code. Our MCP servers are both started and available. Now let me ask Claude to build a query:

“Build a query showing the number of delayed departures per day originating from SFO.”

Claude queries ClickHouse through the Altinity MCP and returns a working query in about 30 seconds. The numbers look correct — let’s stipulate they are and move on.

Now let me ask Claude to create a Grafana dashboard from this:

“Create a Grafana dashboard panel visualizing this query.”

Claude uses the Grafana MCP server to query the Grafana instance, finds the data source named “Altinity,” creates a dashboard, and reports it’s done. Let me reload the Grafana dashboard… and there it is — a nice time series of SFO delayed departures.

Let me add more:

“Expand the dashboard with additional panels.”

About 30 seconds later — it adds a pie chart. The Grafana MCP has write access to my local Grafana instance running in Docker, so the new panel appears immediately.

This is really powerful. Note: one key learning is that LLMs are great for planning and prototyping like this, but once you get something working, reduce it to code. Don’t keep an LLM in the loop for production use — it’s roughly 100,000 times slower than running the query or dashboard directly.

[16:50] — MCP Servers in the Claude.ai Web UI

Robert: You can also register MCP servers in the Claude.ai web UI, not just the command line. In the UI, there’s a connectors section where you can add them. It gives you good visibility into all the tools available and lets you enable or disable them. Very convenient for managing multiple servers.

[18:08] — Skills: Packaged AI Playbooks for ClickHouse

Robert: Now let’s talk about Skills — the second toy we work with heavily. Skills are a very powerful feature of modern AI introduced by Anthropic. They’re packaged playbooks for AI agents. They’re not quite runbooks: a runbook gives you exact steps to execute something, which is not how AI works. Instead, you give the AI pointers to the relevant information for a particular problem, and the model — which already has a huge amount of ground knowledge about ClickHouse — uses that information to orient itself and solve the problem.

A skill directory has one required file: SKILL.md. This file has a header describing what the skill does and when to call it, and then whatever body information you want to include — SQL files, scripts, reference data, anything useful. There’s some structure but not much.

Context efficiency is a key benefit. When you register skills with Claude, it loads only the header from each skill file. Claude uses that header to know when a skill is relevant without consuming the full skill body. When you actually invoke a skill — say, you ask a question about Kafka — it then pulls the whole skill into context. This is very efficient compared to loading everything upfront.

[20:57] — The Altinity Skills Project

Robert: We wrote the Altinity Skills project to capture the lessons from years of ClickHouse support and DBA work. The goal: make you a great ClickHouse DBA without deleting any tables in the process. It gives you the context needed to solve specific problems like “who ate my memory?” It works on any version of ClickHouse — including community builds, Altinity Stable Builds, Antalya builds, and FIPS builds. It’s open source.

To install the skills, use npx to pull them straight from the repo, or clone the project and link them locally:

bash

# Via npx
npx @altinity/altinity-skills

# Or clone and link
git clone https://github.com/Altinity/altinity-skills
cd altinity-skills && npm link

These work with any agent that recognizes skills — we use Claude and Codex heavily.

[22:31] — Handoff to Boris Tushkovich: Skills Demo

Robert: I’m going to turn this over to Boris, who’s going to do some fun stuff with skills — assess database health, generate a nice HTML report, and probably a few other things he finds interesting.

Boris: Okay. So let me start from the beginning. I’ll show you the Altinity skills project on GitHub — we have releases with expert skills. I’ll download a few of them: connection, schema, and overview.

It’s a modular system. You install different skills, and each skill contains several files inside.

I want to show this using the Claude.ai web UI, so you can see how it works without a command line. I’ll go to the new skill section and upload the skill files. Now we have them — ClickHouse connection, instructions, SQL files, and so on.

The second important part is the MCP server connector. I’ll go to customize, find the connectors section, and connect the Altinity MCP server. Now it’s connected — exactly one tool exported: execute_query. That’s enough for our demo.

[26:09] — Demo: Cluster Health Review

Boris: Let me ask something:

“Please review cluster health.”

I didn’t provide the skill name — it should be found automatically by the header. Let’s see.

Claude first decides to read the connection skill to understand how to connect, then decides to read the overview skill and load it into context, then starts reading the SQL files within the skill for discovery, then uses the MCP server to execute different queries.

The process takes some time. You can open another Claude session and ask something different while it’s working.

Let me start a second session in parallel:

“Please use expert schema to review the schema for the on-time database on the same cluster.”

That’s running now. Claude reads the schema skill, finds the tools, and starts working.

Back to the first session — it’s finished. Here’s the report:

• Uptime: 10 hours (in MCP mode)
• Memory usage: OK
• Disk: OK
• Replication: OK
• Background pools: OK
• DDL queue: OK
• System errors: One detached part — quite old, should be deleted
• System log TTL: Marked major because this is a real problem for many ClickHouse installations where customers don’t set TTL for system log tables

Pretty interesting report. Not many problems — that’s a healthy cluster. Recommendations: clean up the detached part, set system log TTLs.

[29:54] — Demo: Schema Review

Boris: Now the schema review is done. Here’s what Claude found:

• Table inventory: The ontime MergeTree fact table, quite large, 39 yearly partitions, big dataset
• Dimension table: single partition
• Problem: Poor compression for one column despite having a low-cardinality String type — could compress better with LowCardinality encoding
• Problem: Many nullable columns — a very common problem in ClickHouse installations where nullable types are used when they’re not needed
• Recommendation: Install skip indexes

Robert: This is great, Boris. One thing to note for customers: we used to ship a custom audit script to do exactly this — collect stats and generate an HTML report. As you can see, frontier models do a really, really good job of this, and this is one of the most promising areas where LLMs can be applied immediately today with few concerns.

[32:26] — Guardrails: Why Not Let the LLM Fix Everything?

Robert: Wouldn’t it be great if you could use an LLM to carry out those recommendations? For example, there was a detached part — why doesn’t the LLM just go ahead and delete it?

Well, here’s why. This is not hypothetical — this is from Hacker News (I removed the profanity): someone’s AI deleted all their tables. They were very unhappy. And in fact, we’re dealing with a customer case this morning where it looks like exactly this may have happened in a production database we were assisting with migration. We still have backups, so hopefully they’ll recover. But this is a real and serious problem.

Here’s how it happens with agents. A developer uses Claude Code with the Altinity MCP server — Claude can access ClickHouse. If the accounts in use have write access, Claude can drop a table through the MCP. Worse, if Claude sees clickhouse-client in the environment and knows the login credentials, it can log in directly with DBA-level access and do whatever it wants.

[35:28] — Solution 1: MCP Read-Only Mode

Robert: The first solution is to lock down the Altinity MCP server. There’s a feature called read-only mode that parses all SQL coming in through the execute_query tool. It’s like SQL injection protection — it allows SELECT, SHOW DATABASES, SHOW TABLES, DESCRIBE TABLE, and similar inspection commands. Anything else — DDL, INSERT, DROP — is blocked at the MCP layer before it reaches ClickHouse. You get an error instead of data loss.

[36:11] — Solution 2: OAuth 2.0 Authentication

Robert: The second solution is using OAuth 2.0 / OIDC for authentication. This enables broad read-only access without storing credentials in the MCP configuration, and it lets you give many people basic ClickHouse access without turning them all into DBAs.

Here’s how the flow works with the Altinity MCP in broker-off mode:

1. Claude connects to the MCP server and wants to log in
2. The MCP server provides a reference to a “well-known” OAuth resource
3. Claude finds the identity provider (e.g., Google), authenticates, and receives a JWT (JSON Web Token)
4. Claude uses that JWT for all subsequent MCP calls
5. The MCP server proxies the JWT through to ClickHouse

On the ClickHouse side, Altinity’s Antalya builds have built-in OAuth token processing. You configure a token_processor that points to the identity provider for validation:

xml

<clickhouse>
    <auth_config>
        <use_token_based_auth>1</use_token_based_auth>
        <auth_server>https://accounts.google.com</auth_server>
    </auth_config>
</clickhouse>

ClickHouse validates the token against the IDP (and caches the result for ~60 seconds). Then user_directories maps all OAuth token users to a specific role:

xml

<user_directories>
    <token_based_users>
        <default_role>ooth_demo</default_role>
    </token_based_users>
</user_directories>

Where ooth_demo is a read-only role. DBAs keep their own separate credentials and log in from a separate location.

For non-Antalya builds, the chwt-validator helper project validates JWTs via ClickHouse’s password validation hook, making OAuth work even on older community releases.

[42:09] — Demo: Read-only Enforcement

Boris: Let me demonstrate this in Claude.ai with a non-Antalya ClickHouse build using the CHWT validator.

The OAuth flow runs automatically. Now let me check:

“Show my grants.”

Claude executes the query through the MCP, and I can see all my permissions in ClickHouse — the user has full access at the database level.

“Please create a database named test.”

Claude attempts it… and it’s blocked. Despite having all permissions in ClickHouse, the MCP server’s read-only layer denies the operation. I have only a read-only tool and cannot write, create databases, alter tables, or perform any DDL.

Robert: That demonstrates the idea perfectly. And it’s interesting — MCP as a security layer, not just a data access protocol. Boris, would you add anything?

Boris: MCP is basically a protocol, like HTTP. We’re seeing the first attempts to do something useful with it. In the future, I expect we’ll see full-scale applications with complicated functionality and interesting limitations on agent access to data. This is our direction — thinking about how to prevent dangerous agent access to client data.

[48:37] — Roadmap and Key Learnings

Robert: Let’s cover what we’ve learned and what comes next.

Key learnings so far:

• Lower-cost models like Claude Sonnet work really well for many things — faster and cheaper. Only escalate to Opus when the response quality isn’t good enough.
• The Altinity Skills project is ready to use now. Pull it, try it. It captures years of DBA knowledge and makes it accessible to any agent.
• Reduce to code. LLMs are great for planning and prototyping. Once you have something working, turn it into code that your systems run repeatedly without needing an LLM in the loop.
• MCP is a promising way to create barriers that protect data while allowing LLMs to do everything safely. Read-only mode makes it hard (though not impossible) to delete data.
• OAuth looks key for enabling broad access directly to data — making ClickHouse data available to everyone safely, from trading floor analysts to observability engineers.

Roadmap:

• Improving Altinity Skills: adding Kubernetes-focused skills, not just DBA skills
• MCP access baked into Altinity.Cloud — being productized now
• Simplifying OAuth documentation and tooling (practically nobody understands OAuth correctly because it’s complex and every product implements it differently)
• Agent optimization: speed, cost, reliability, consistent answers as models change
• Local model support: everything demoed today was shipped to Anthropic’s servers and is in their logs. For sensitive production data you need local models where data stays local
• Introducing safe agents: log analysis, alerting, automated fix recommendations for non-destructive operations

[55:22] — Resources

Robert: Scan the QR code for the Altinity Skills project on GitHub. You can also find the Altinity MCP server there. Both are Apache 2.0 licensed.

For managed ClickHouse with built-in OAuth support, see Altinity.Cloud. For production-certified builds including Antalya with OAuth integration, see Altinity Stable Builds.

[56:03] — Q&A: MCP for DDL

Q: When it comes to using MCP for DDL statements, where are we?

Robert: We don’t do it for production — too unpredictable, and the incident we’re investigating this morning may be exactly this. Agents are famous for ignoring guidance and doing what they think is interesting.

Boris: That said, I use MCP for DDL in development and staging all the time. I’ll ask Claude to create a schema, fill it with data, run five experiments in a Docker container with a specific ClickHouse version, and write a nice report. Claude creates the container, creates the schema, loads data, runs experiments, and writes the report. In that limited non-production environment — no problem at all. The distinction is production vs. non-production, not the protocol itself.

Robert: That’s a really key point. And it’s similar to the point about sending demo data to a hosted LLM — we don’t care who sees demo data. But production data is different. We’ll be exploring these topics in future presentations and in-person events in San Francisco, Seattle, and Los Angeles at the end of June.

Thank you to Boris for all his work on this — a huge amount of the content comes from him. We’re at the time, but if you have questions, contact us on our Slack or reach out on LinkedIn.

FAQ

What is the Altinity MCP server, and what does it do?

The Altinity MCP server is an open-source (Apache 2.0) Go implementation of a Model Context Protocol server for ClickHouse. It provides AI agents with a standardized execute_query tool that maps to SQL queries against ClickHouse databases. It supports multiple transport protocols (STDIO, SSE, HTTP), integrates with OAuth 2.0 / OIDC for token-based authentication, and includes a read-only mode that parses incoming SQL and blocks all write operations before they reach ClickHouse.

What are Altinity Skills and how do they reduce context consumption?

Altinity Skills are packaged DBA playbooks stored as directories containing a SKILL.md file (with a header and body) and optional SQL and script files. When registered with an AI agent, only the SKILL.md header is loaded into the context window — the agent reads just enough to know when to apply the skill. When you ask a question that matches a skill, the agent loads the full skill body into context and uses it to guide its investigation. This lazy loading dramatically reduces context usage compared to loading all reference material upfront. The Altinity Skills project is open source, available at github.com/Altinity/altinity-skills.

What is the main safety risk when using LLMs with ClickHouse?

The primary risk is allowing AI agents to perform write operations on production data. If an AI agent has access to ClickHouse credentials with write permissions — either through an MCP server or by discovering the ClickHouse client in its environment — it may drop tables, delete data, or perform destructive DDL operations based on its own judgment, without prompting. Real incidents of this kind have occurred. The recommended mitigation is to enable readonly mode in the Altinity MCP server and use OAuth-based read-only roles so that agent-accessible credentials have only SELECT access.

How does OAuth 2.0 authentication work with the Altinity MCP server and ClickHouse?

In OAuth mode, the Altinity MCP server does not store credentials. When an AI agent connects, the MCP server directs it to an identity provider (such as Google). The agent authenticates, receives a JWT, and passes that JWT on all subsequent calls. The Altinity MCP proxies the JWT to ClickHouse. Altinity’s Antalya builds have native OAuth token processing: ClickHouse validates the JWT against the configured IDP, caches the result, and uses user_directories configuration to assign all OAuth token users a read-only role automatically. For community ClickHouse builds, the chwt-validator helper project provides JWT validation via a password validation hook.

When is it safe to allow AI agents to perform DDL (CREATE, DROP, ALTER) in ClickHouse?

DDL through AI agents is appropriate in development and staging environments — for example, in a Docker container where an agent creates schemas, loads test data, runs experiments, and generates reports. In production environments, DDL through agents is not recommended because agents can ignore instructions and execute destructive commands based on their own judgment. The boundary is production vs. non-production, not the MCP protocol itself.

What is the Altinity Antalya build, and why does it matter for AI integration?

Antalya is Altinity’s technology preview build of ClickHouse that includes features ahead of standard LTS releases, including native OAuth 2.0 / OIDC token authentication and processing. This allows ClickHouse to validate JWT tokens directly against identity providers like Google without additional helper software, making it straightforward to give AI agents secure, read-only access to ClickHouse data through standard SSO providers.

© 2025 Altinity, Inc. All rights reserved. Altinity®, Altinity.Cloud®, and Altinity Stable® are registered trademarks of Altinity, Inc. ClickHouse® is a registered trademark of ClickHouse, Inc. Altinity is not affiliated with or associated with ClickHouse, Inc. Kubernetes, MySQL, and PostgreSQL are trademarks and property of their respective owners.