How to integrate ClickHouse MCP with Atomic Agent

Connect Atomic Agent to ClickHouse MCP. List top 10 slow queries last hour, aggregate error rates by service today, and more using natural language, with authentication handled for you.

ClickHouse MCP logoClickHouse MCP
Dcr Oauth

ClickHouse MCP is ClickHouse Cloud's managed observability query service via the ClickStack MCP server. Use it to run fast analytical queries against observability data with managed access.

32 Tools

Introduction

Atomic Agent is an open-source AI agent that runs on your machine and supports local models through llama.cpp. Connect it to 1,500+ apps through Composio, including ClickHouse.

This guide uses Atomic Agent's built-in Composio integration. You need Atomic Agent v0.5.6 or later, your own Composio API key, and a ClickHouse account. See the Atomic Agent documentation for installation instructions.

Also integrate ClickHouse MCP with

How Atomic Agent connects to ClickHouse

Atomic Agent connects to Composio's Tool Router over Streamable HTTP MCP. It discovers the tools needed for your request, and Composio handles account authentication.

Execution and account-connection tools follow Atomic Agent's configured approval policy. Review any approval prompt before allowing an action on your connected account.

Connect ClickHouse to Atomic Agent

  1. Sign up or sign in to the Composio dashboard. Copy your API key.
  2. In Atomic Agent, open the Integrations tab and select Composio. Select API key, press e, paste the key, and press Enter. The tools become available immediately, without a restart.
  3. Ask Atomic Agent to do something in ClickHouse. It searches Composio for the right tool.
  4. On first use, open the sign-in link returned in the chat. Connect your ClickHouse account, then return to Atomic Agent to continue.

Headless setup

Add the following line to ~/.atomic-agent/.env, replacing YOUR_COMPOSIO_API_KEY with your key. Start Atomic Agent after saving the file.

bash
COMPOSIO_API_KEY=YOUR_COMPOSIO_API_KEY

What is the ClickHouse MCP server, and what's possible with it?

The ClickHouse MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your ClickHouse account. It provides structured and secure access so your agent can perform ClickHouse operations on your behalf.

Use ClickHouse from Atomic Agent

With your account connected, ask Atomic Agent to work with ClickHouse in natural language. You can connect more apps through the same Composio integration as you need them.

Visit the Atomic Agent website or inspect the Atomic Agent source code.

Troubleshooting

Why is my API key rejected?

Copy the key directly from the Composio dashboard. Atomic Agent requires ASCII characters because it sends the key in an HTTP header. Remove any extra characters introduced when copying.

Why are Composio tools unavailable after saving a key?

Check that you use Atomic Agent v0.5.6 or later and that Composio is enabled in your configuration. A "composio": { "enabled": false } setting disables the integration while keeping the saved key on disk.

Does Composio have a free plan?

The Hobby plan includes 100,000 tool calls per month. Composio-managed OAuth apps have a lower included allowance. See Composio pricing for the current limits that apply to your connection.

TOOLS

Supported Tools

Every ClickHouse MCP action and event your agent gets out of the box.

Clickstack delete dashboard

Permanently delete a dashboard by ID.

Clickstack delete source

Permanently delete a data source by ID.

Clickstack delete webhook

Permanently delete a webhook by ID.

Clickstack describe metric

DRILL-DOWN: Use after clickstack_list_metrics (or after a clickstack_describe_source sample) to get attribute keys, sampled values, unit, and description for a specific (metricName, kind) pair.

Clickstack describe source

CALL THIS BEFORE WRITING QUERIES — prevents unknown-column errors.

Clickstack emerging signals

Detect what is NEW or GONE between an earlier baseline window and a current window — log/event patterns that emerged, ramped up, or stopped.

Clickstack event deltas

Rank the properties of two row groups (logs or trace spans) by how much their value distributions differ.

Clickstack event patterns

Discover the most common log messages and event patterns.

Clickstack get alert

Without an ID: list all alerts as a high-level summary (id, name, state, source, interval).

Clickstack get dashboard

Without an ID: list all dashboards (returns IDs, names, tags).

Clickstack get dashboard tile

Retrieve a single tile from a dashboard by tileId.

Clickstack get saved search

Without an ID: list all saved searches as a high-level summary (id, name, tags).

Clickstack get source filter values

List the available values for the required source filter columns on a single source.

Clickstack get webhook

List available webhook destinations (id, name, service type).

Clickstack list metrics

DISCOVERY: Use this after clickstack_describe_source when you need more metric names than the per-kind sample shows, or when you want to narrow by kind / name pattern / time window.

Clickstack list sources

List all data sources (logs, metrics, traces) and database connections available to this team.

Clickstack list teams

List all teams the current user belongs to and identify which team is active for this session.

Clickstack patch dashboard

Make targeted updates to a dashboard without resubmitting the full object.

Clickstack query tile

Execute the query for a specific tile on an existing dashboard.

Clickstack query tiles

Run the queries for many tiles of a dashboard in ONE call and return a compact per-tile success/failure summary.

Clickstack save alert

Create a new alert (omit id) or update an existing one (provide id).

Clickstack save dashboard

Create a new dashboard (omit id) or update an existing one (provide id).

Clickstack save saved search

Create a new saved search (omit id) or update an existing one (provide id).

Clickstack save source

Create a new data source (omit id) or update an existing one (provide id) so shipped telemetry becomes queryable.

Clickstack save webhook

Create a new webhook (omit id) or update an existing one (provide id).

Clickstack search

Browse individual log/event/trace rows.

Clickstack search dashboards

Search dashboards by name and/or tags.

Clickstack sql

Execute raw ClickHouse SQL.

Clickstack table

Compute aggregated metrics as a table, single number, pie chart, or bar chart.

Clickstack timeseries

Plot metrics over time as a line or stacked bar chart.

Clickstack trace top time consuming operations

Given a parent-span filter and a time window, return the child operations contributing the most cumulative time across all traces matching the parent filter.

Clickstack trace waterfall

Fetch all spans in ONE trace and return them as a parent/child waterfall, pre-ordered for human-readable display.

FAQ

Frequently asked questions

With a standalone ClickHouse MCP server, the agents and LLMs can only access a fixed set of ClickHouse tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from ClickHouse and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Atomic Agent fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right ClickHouse tools.

Yes, absolutely. You can configure which ClickHouse scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your ClickHouse data and credentials are handled as safely as possible.

Start with ClickHouse MCP.It takes 30 seconds.

Managed auth, hosted MCP servers, and every ClickHouse MCP tool your agent needs.Free to start.

Start building