Skip to main content
ClickHouse Cloud is a serverless, columnar data warehouse for real-time analytics and observability. The ClickHouse MCP server lets you run SQL, manage services and backups, configure ClickPipes, track costs, and operate the ClickStack observability plane (dashboards, alerts, sources) using natural language.

​
What Can It Do?

  • Run SQL against any ClickHouse Cloud service and return structured results
  • Manage services by listing them, starting, or stopping on demand
  • Inspect backups and backup schedules for each service
  • Manage ClickPipes to monitor streaming ingestion jobs
  • Track organization costs with daily billing and usage data
  • Operate ClickStack observability with dashboards, alerts, and data sources

​
Where to Use It

Add ClickHouse as a tool to any agent. The agent can then interact with your data and observability plane conversationally, choosing the right actions based on context. To add an MCP tool to your agent:
  1. Open your agent’s configuration
  2. Click Add tools → Connect an app with MCP
  3. Search for the integration and select it
  4. Authenticate with your ClickHouse Cloud API key
You can control which tools your agent has access to. After adding an integration, click on it to enable or disable specific tools based on what your agent needs.

​
In Workflows (Via Agent Node)

For automated pipelines, use an Agent Node with ClickHouse tools. This gives you the flexibility of an agent within a deterministic workflow.

​
As a Custom MCP Node

You can also create a standalone MCP node for a specific action. This generates a reusable node that performs one task, useful when you need the same operation repeatedly in workflows.
To create a custom MCP node:
  1. Go to your node library and search for the integration
  2. Click Create a node with AI
  3. Describe the specific action you want (e.g., “Query the events table for the last 24 hours”)
  4. Test the node and save it for reuse
Custom MCP nodes are single-purpose by design. For tasks that require multiple steps or dynamic decision-making, use an agent instead.

​
Authentication

ClickHouse uses a Key ID / Key Secret API key pair plus a database user and password for SQL access.
  1. In the ClickHouse Cloud console, go to Organization Settings → API Keys → New API Key
  2. Assign a role that matches what you want the MCP to do (Developer for read-only, Admin for writes and lifecycle operations)
  3. Copy the Key ID and Key Secret (the secret is shown once)
  4. Get your Database User (defaults to default) and Database Password from Service Settings in the Cloud console
See Managing API Keys for full details.

​
Available Tools

​
Example Prompts

Use these with your agent or in the Agent Node: Run a query:
List services:
Start a service:
Check backups:
Monitor ingestion:
Track cost:
Create an alert:

​
Troubleshooting

Agents are smart enough to chain multiple API calls together. For example, asking “Start the analytics service and run a smoke-test query” will list services, start the right one, wait, and then run the query. If results seem off, check the agent’s step-by-step reasoning.

​
Need Help?