X (Twitter)LinkedInGitHubDiscordYouTube

ClickHouse MCP for AI Agents

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with ClickHouse MCP or direct API to run SQL queries, aggregate observability metrics, filter logs, and export query results through natural language.

Get started for freeGet a demo
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

Try ClickHouse MCP now

Type what you want done — sign in and watch it run live in the Tool Router playground.

TOOL ROUTER PLAYGROUND
ClickHouse MCP
Try asking
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.

SETUP GUIDE

Connect ClickHouse MCP Tool with your Agent

1

Install Composio

typescript
npm install @composio/core ai @ai-sdk/openai @ai-sdk/mcp
Install the Composio SDK for Python or TypeScript
2

Initialize Client and Create Tool Router Session

typescript
import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your-api-key' });
const session = await composio.create('your-user-id');
console.log(`Tool Router session created: ${session.mcp.url}`);
Import and initialize the Composio client, then create a Tool Router session for ClickHouse MCP
3

Connect to AI Agent

typescript
import { openai } from '@ai-sdk/openai';
import { experimental_createMCPClient as createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';

const client = await createMCPClient({
  transport: {
    type: 'http',
    url: session.mcp.url,
    headers: {
      'x-api-key': 'your-composio-api-key',
    },
  },
});

const tools = await client.tools();
const { text } = await generateText({
  model: openai('gpt-4o'),
  tools,
  messages: [{
    role: 'user',
    content: 'YOUR_SPECIFIC_PROMPT_HERE'
  }],
  maxSteps: 5,
});

console.log(`Agent: ${text}`);
Use the MCP server with your AI agent (Anthropic Claude or Mastra)
SETUP GUIDE

Connect ClickHouse MCP API Tool with your Agent

1

Install Composio

typescript
npm install @composio/openai
Install the Composio SDK
2

Initialize Composio and Create Tool Router Session

typescript
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIResponsesProvider } from '@composio/openai';

const composio = new Composio({
  provider: new OpenAIResponsesProvider(),
});
const openai = new OpenAI({});
const session = await composio.create('your-user-id');
Import and initialize Composio client, then create a Tool Router session
3

Execute ClickHouse MCP Tools via Tool Router with Your Agent

typescript
const tools = session.tools;
const response = await openai.responses.create({
  model: 'gpt-4.1',
  tools: tools,
  input: [{
    role: 'user',
    content: 'YOUR_SPECIFIC_PROMPT_HERE'
  }],
});
const result = await composio.provider.handleToolCalls(
  'your-user-id',
  response.output
);
console.log(result);
Get tools from Tool Router session and execute ClickHouse MCP actions with your Agent

Why Use Composio?

AI Native ClickHouse MCP Integration

  • Supports both ClickHouse MCP and direct API based integrations
  • Structured, LLM-friendly schemas for reliable tool execution
  • Rich coverage for reading, writing, and querying your ClickHouse MCP data

Managed Auth

  • Built-in OAuth handling with automatic token refresh and rotation
  • Central place to manage, scope, and revoke ClickHouse MCP access
  • Per user and per environment credentials instead of hard-coded keys

Agent Optimized Design

  • Tools are tuned using real error and success rates to improve reliability over time
  • Comprehensive execution logs so you always know what ran, when, and on whose behalf

Enterprise Grade Security

  • Fine-grained RBAC so you control which agents and users can access ClickHouse MCP
  • Scoped, least privilege access to ClickHouse MCP resources
  • Full audit trail of agent actions to support review and compliance
FRAMEWORKS

Use ClickHouse MCP with any AI Agent Framework

Choose a Framework you want to connect ClickHouse MCP with

ChatGPT Work logo

ChatGPT Work

Use ClickHouse MCP with ChatGPT Work

Claude Cowork logo

Claude Cowork

Use ClickHouse MCP with Claude Cowork

Hermes logo

Hermes

Use ClickHouse MCP with Hermes

FAQ

Frequently asked questions

Yes, ClickHouse MCP requires you to configure your own Dcr Oauth credentials. Once set up, Composio handles secure credential storage and management for you.

Yes! Composio's Tool Router enables agents to use multiple toolkits. Learn more.

Composio is SOC 2 and ISO 27001 compliant with all data encrypted in transit and at rest. Learn more.

Composio maintains and updates all toolkit integrations automatically, so your agents always work with the latest API versions.

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