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
In Agents (Recommended)
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:
- Open your agent’s configuration
- Click Add tools → Connect an app with MCP
- Search for the integration and select it
- 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:
- Go to your node library and search for the integration
- Click Create a node with AI
- Describe the specific action you want (e.g., “Query the events table for the last 24 hours”)
- 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.
- In the ClickHouse Cloud console, go to Organization Settings → API Keys → New API Key
- Assign a role that matches what you want the MCP to do (Developer for read-only, Admin for writes and lifecycle operations)
- Copy the Key ID and Key Secret (the secret is shown once)
- Get your Database User (defaults to
default) and Database Password from Service Settings in the Cloud console
See Managing API Keys for full details.
| Tool | Description |
|---|
| Execute Query | Run a SQL query against a ClickHouse Cloud service |
| List Organizations | List your Cloud organizations or fetch one by id |
| List Services | List services in an organization or fetch one by id |
| Update Service State | Start or stop a ClickHouse Cloud service |
| List Service Backups | List backups for a service or fetch one by id |
| Get Service Backup Configuration | Get the backup schedule and retention for a service |
| List ClickPipes | List ClickPipes on a service or fetch one by id |
| Get Organization Cost | Retrieve daily billing and usage cost for an organization |
| List Dashboards | List ClickStack dashboards on a service or fetch one by id |
| Create Dashboard | Create a ClickStack dashboard |
| Update Dashboard | Update a ClickStack dashboard |
| Delete Dashboard | Delete a ClickStack dashboard |
| List Alerts | List ClickStack alerts on a service or fetch one by id |
| Create Alert | Create a ClickStack alert tied to a dashboard tile or saved search |
| Update Alert | Update a ClickStack alert |
| Delete Alert | Delete a ClickStack alert |
| List Sources | List ClickStack data sources configured on a service |
Example Prompts
Use these with your agent or in the Agent Node:
Run a query:
Run "SELECT count() FROM events WHERE event_date = today()" on my production service
Show me all ClickHouse services in my organization and their current state
Start the "analytics-prod" service
List the latest backups for the analytics-prod service and its backup retention policy
List all ClickPipes on the analytics-prod service and flag any that are not running
Show me the daily ClickHouse Cloud cost for my organization over the last 7 days
Create an alert on the "API Errors" dashboard tile that fires when errors exceed 100 per hour
Troubleshooting
| Issue | Solution |
|---|
| Authentication failing | Verify the Key ID, Key Secret, and database credentials. The Key Secret is only shown once when created. |
| Query returns no data | Confirm you’re targeting the right service and that the service is running. Use List Services first. |
| Action not permitted | Check that your API key role (Developer vs Admin) has the permissions the tool needs. |
| Tool not available | Verify the tool is enabled in your agent’s MCP configuration |
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?
