Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ToolDescription
Execute QueryRun a SQL query against a ClickHouse Cloud service
List OrganizationsList your Cloud organizations or fetch one by id
List ServicesList services in an organization or fetch one by id
Update Service StateStart or stop a ClickHouse Cloud service
List Service BackupsList backups for a service or fetch one by id
Get Service Backup ConfigurationGet the backup schedule and retention for a service
List ClickPipesList ClickPipes on a service or fetch one by id
Get Organization CostRetrieve daily billing and usage cost for an organization
List DashboardsList ClickStack dashboards on a service or fetch one by id
Create DashboardCreate a ClickStack dashboard
Update DashboardUpdate a ClickStack dashboard
Delete DashboardDelete a ClickStack dashboard
List AlertsList ClickStack alerts on a service or fetch one by id
Create AlertCreate a ClickStack alert tied to a dashboard tile or saved search
Update AlertUpdate a ClickStack alert
Delete AlertDelete a ClickStack alert
List SourcesList 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
List services: 
Show me all ClickHouse services in my organization and their current state
Start a service: 
Start the "analytics-prod" service
Check backups: 
List the latest backups for the analytics-prod service and its backup retention policy
Monitor ingestion: 
List all ClickPipes on the analytics-prod service and flag any that are not running
Track cost: 
Show me the daily ClickHouse Cloud cost for my organization over the last 7 days
Create an alert: 
Create an alert on the "API Errors" dashboard tile that fires when errors exceed 100 per hour

​
Troubleshooting

IssueSolution
Authentication failingVerify the Key ID, Key Secret, and database credentials. The Key Secret is only shown once when created.
Query returns no dataConfirm you’re targeting the right service and that the service is running. Use List Services first.
Action not permittedCheck that your API key role (Developer vs Admin) has the permissions the tool needs.
Tool not availableVerify 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?