Configuring MCP

The Altinity MCP server lets you expose your ClickHouse® data to an LLM. It exposes tools that let the LLM list tables, describe schemas, and run queries, and it enforces read-only mode by default. Here are the steps for getting everything working:

• Enable the MCP server for your environment
• Enable the MCP server for your cluster
• Add the MCP server's connection to your LLM
• Authenticate to your LLM
• Create a new ClickHouse user
• Ask the MCP what it can do and start exploring your data

We’ll go through those steps next.

Enabling the MCP server for your environment

Before you can use the MCP server with a cluster, you have to enable it at the environment level. The MCP configuration documentation in the Administrator Guide has all the details. Be aware that you must have the appropriate privileges to edit an environment’s settings, so you may need to contact your administrator. Once the MCP server is enabled at the environment level, you’re ready for the next step.

Enabling the MCP server for your cluster

Enabling the MCP server is pretty simple. If things are set up at the environment level, but this cluster doesn’t have MCP enabled, you’ll see something like this:

Figure 1 - Initial view: MCP not enabled for this cluster

If you need to make changes to the environment-level MCP settings, click the icon to go to the Environment configuration panel. The text here indicates that the MCP server has read-only access, and it lists the client redirect URLs that the MCP server has. You can change the redirect URLs in the Environment-level MCP configuration dialog.

When you click the button, you’ll be advised that saving your changes may cause a restart:

Figure 2 - Confirming your changes

You’ll see a status message at the bottom of the panel:

Figure 3 - MCP being enabled message

It will likely be a couple of minutes before your cluster’s configuration has been updated. Once the update is complete, the MCP configuration dialog will look something like this:

Figure 4 - The MCP configuration dialog: MCP enabled for this cluster

The panel now has information that we’ll need to connect everything together. Here are the details:

• MCP environment settings - Again, if you need to configure the MCP at an environment level, click the icon to go directly to the MCP configuration dialog for the environment.
• Read-only mode - The icon means that read-only mode is activated. (You can disable this at the environment level, but proceed with caution.)
• Client redirect URLs - The redirect URLs defined at the environment level. In Figure 4 above, we’ve defined URLs for Claude and ChatGPT. LLMs use these URLs to handle authentication.
• Connection configuration example - This is JSON to define the MCP to an agent other than Claude or ChatGPT.
• Create a user example - This is the syntax to create a new ClickHouse user. We can create a user named maddie@example.com, then go to the LLM and authenticate as that user. The LLM will then pass an access token to the MCP when it wants to work with ClickHouse. If the access token matches the user we defined, ClickHouse will process the LLM’s request. (It may reject the request for some reason, but it will at least try. If the access token doesn’t represent a user we’ve defined to ClickHouse, the request won’t be evaluated at all.)

Adding the MCP server’s connection to your LLM

With the MCP server enabled for your cluster, you need to define it to your LLM. Looking at Figure 4 above, the JSON tells an LLM to go to mcp.altinity-maddie.altinity.cloud/mcp. With Cursor, for example, save the JSON in the file ~/.cursor/mcp.json.

Other LLMs have a graphical interface. For example, here’s how to add the Altinity connector to Claude:

Go to the Settings menu and select Connectors, then Add custom connector from the dropdown menu:

Figure 5 - Adding a custom connector to Claude

Give the connector a name and enter the URL from Figure 4 above:

Figure 6 - Entering the connector’s URL

With the connector defined, you’ll be asked to actually connect to the MCP server:

Figure 7 - Making the connection

That will redirect you to the LLM’s login screen.

Authenticating to your LLM

When you add the connection, you’ll see something like this:

Figure 8 - Authenticating with an IdP (Auth0)

As an example, let’s say we logged in as maddie@example.com.

If all goes well, you’ll be asked to confirm what you want to enable the connector to do:

Figure 9 - Setting the connector’s permissions

You can set each of the connector’s permissions to Always allow, Needs approval, or Blocked. In Figure 8, all read-only tools are always allowed to run, and the write/delete tool needs approval. If your prompt requires the LLM to do something that needs approval, you’ll see something like this:

Figure 10 - Claude needs approval

Creating a new ClickHouse user

This step is straightforward; use the email address you authenticated with the IdP to run the command shown in Figure 4:

CREATE USER `maddie@example.com` IDENTIFIED WITH http SERVER 'mcp_auth' SCHEME 'BASIC'

Next, use ClickHouse’s RBAC functions to say what that user can do:

GRANT SELECT ON raw.* TO `maddie@example.com`;
GRANT SELECT ON analytics.* to `maddie@example.com`;
GRANT SELECT ON reports.* to `maddie@example.com`;
GRANT SELECT ON system.query_log TO `maddie@example.com`;
GRANT SELECT ON system.processes TO `maddie@example.com`;

This simple example gives grants to the user at a per-database and per-table level, but you have full use of ClickHouse’s roles and grants to control access to your data.

At this point, everything is set up. Whenever the LLM needs to work with your data, it passes the access token from the LLM to the Altinity MCP server. The MCP server passes the LLM’s request and the access token to ClickHouse. If the access token matches a user defined to ClickHouse and that user has permission to perform the LLM’s request, ClickHouse will run the request, return the results to the MCP server, and the MCP server will return the results to the LLM.

NOTE: If you’re running Altinity’s Antalya build and you have an OAuth server, you can configure Antalya to use tokens from an OAuth server to create users automatically. See the Antalya OAuth documentation for details.

Asking what the Altinity connector can do

With everything connected and configured, you can ask the LLM what the connector can do. A typical interaction might look like this:

You:

find out what things the altinity mcp connector can do, including descriptions

Cursor’s response:

Your Altinity MCP (user-altinity-aws-byoc-doug-mcp-altinity-cloud) exposes 4 tools plus a library of ClickHouse diagnostic skills.

Tools

Your cluster here is sales-data.

From there you can start working with the data in your ClickHouse cluster. Here’s a sample series of prompts against sample data gated by the MCP server at mcp.demo.altinity.cloud/mcp/antalya:

• use the Altinity connector until further notice. what databases are available?
• what’s in the ontime database?
• what are the airlines with the worst on-time performance?
• let’s look at JetBlue since COVID. are their numbers consistent through the year, or are there times when they’re worse than normal?
• are there particular airports or regions of the country that are worse than others? NYC is pretty notorious for delays; what percentage of JetBlue’s flights are there?
• how much of their problem is weather delay, and how does weather delay vary across the worst airports?

And so on. None of these prompts involve SQL or even any awareness of the database schema on your part. Here we’re just asking questions based on a high-level understanding of what the dataset contains. The LLM figures out how to query the database, and the MCP server makes sure the LLM can’t do anything we don’t want it to do.