# ClickHouse (Vector Search) MCP for AI Agents AI Agent Connect

> ClickHouse (Vector Search) MCP lets your AI agent run SQL queries, manage schemas, and perform high-speed vector searches directly on your ClickHouse cluster. It connects your analytical data and embeddings to your agent, allowing for natural language data exploration, real-time report generation, and automated cluster auditing. This means you can stop switching tabs and start getting answers in your chat interface.

## Overview
- **Category:** ai-frontier
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_567ij3B5hJvT6KRM8Z5LcFbGNttrwDvwD2OPp6c2/ai-agent-connect
- **Tags:** olap, vector-embeddings, sql-execution, high-performance-data, real-time-analytics

## Description

ClickHouse (Vector Search) MCP lets you put your ClickHouse cluster under the control of your AI agent. You can manage your schemas, run SQL queries, and perform high-speed vector searches without leaving your chat interface. Instead of jumping between your terminal and a database GUI, you can just tell your agent to find specific records or summarize a dataset. It handles the DML, DDL, and SELECT queries for you, and even pulls in internal structural states like compression ratios to help you audit your cluster health. Since Vinkius hosts this Connector, you can connect it to your existing workflow in minutes. It turns your database into a conversational tool where you can verify data distributions or debug vector similarity searches on the fly. You get to spend less time on syntax and more time on the actual analysis.

## Tools

### execute_sql
Run any DML, DDL, or SELECT query against your cluster. This lets you manage data and generate reports using only natural language.

### vector_search
Identify records based on mathematical distance traces for embeddings. This makes it easy to find similar items using cosine or L2 metrics.

### list_databases
Show all the top-level schemas in your ClickHouse cluster. This helps you navigate your data environment quickly.

### list_tables
Retrieve the exact tables and limits inside a specific database. Use this to see what data is available for querying.

### describe_table
Pull the schema properties and column types for an active table. This helps you understand your data structure without manual inspection.

### get_table_stats
Pull internal states like row counts and compression ratios. Use this to monitor your cluster health and storage efficiency.

### get_version
Identify the active cluster limits and binary support versions. This helps you verify if your instance supports specific features like HNSW.

## Prompt Examples

**Prompt:** 
```
What's the current storage size of our 'sales_data' table?
```

**Response:** 
```
The 'sales_data' table is currently taking up 450MB of space. It has a compression ratio of 4.2x and contains about 1.2 million rows. Everything looks healthy.
```

**Prompt:** 
```
Find the 3 most similar items to this product vector: [0.12, -0.5, 0.8]
```

**Response:** 
```
I've processed that vector. Here are the top 3 matches from your 'products' table:

| Product ID | Score | Name |
|---|---|---|
| P-902 | 0.98 | Wireless Earbuds |
| P-112 | 0.94 | Noise Cancelling Headphones |
| P-443 | 0.91 | Bluetooth Speaker |
```

**Prompt:** 
```
List all the databases in our cluster.
```

**Response:** 
```
I found 4 databases in your ClickHouse cluster:

*   `default`
*   `analytics_prod`
*   `vector_store`
*   `system`

Which one would you like to look into?
```

## Capabilities

### Run arbitrary SQL queries
Execute DML, DDL, or SELECT statements to manage your data.

### Perform vector similarity searches
Identify records based on mathematical distance traces for embeddings.

### Inspect database schemas
View tables and column types including specialized Array(Float32) vector types.

### Audit cluster health
Extract internal structural states, row counts, and compression ratios.

### Check instance limits
Identify precise active cluster limits and binary support like HNSW.

## Use Cases

### Finding similar products
A shopper asks for items like a specific product. The agent uses `vector_search` to find the top matches.

### Quick report generation
An analyst asks for last month's sales by region. The agent uses `execute_sql` to pull and summarize the data.

### Cluster health check
A DBA asks about storage efficiency. The agent uses `get_table_stats` to report compression ratios and row counts.

### Schema discovery
A developer needs to know what columns are in the 'users' table. The agent uses `describe_table` to show the schema.

## Benefits

- Skip the manual SQL writing by using `execute_sql` to run queries with plain English commands.
- Find similar items instantly using `vector_search` to handle cosine and L2 distance math.
- Get a clear picture of your storage efficiency with `get_table_stats` pulling compression ratios.
- Understand your data structure at a glance by using `describe_table` to inspect schemas.
- Manage your entire database organization by using `list_databases` and `list_tables` from your chat.

## How It Works

The bottom line is you get a natural language interface for your entire ClickHouse data environment.

1. Enter your ClickHouse URL, username, and password into the Connector configuration.
2. Connect your preferred AI client to the Vinkius catalog.
3. Ask your agent to run a query or find a vector match.

## Frequently Asked Questions

**Can the ClickHouse (Vector Search) MCP run my custom SQL queries?**
Yes, it can. You can ask your agent to run any DML or SELECT statements, and it will execute them on your cluster and give you the results directly.

**How does ClickHouse (Vector Search) handle vector embeddings?**
It uses the `vector_search` tool to find records based on mathematical distances like cosine or L2. This makes it easy to find similar items in your data using natural language.

**Can I use ClickHouse (Vector Search) to check my database health?**
You can. The Connector can pull internal stats like row counts and compression ratios, so you can ask your agent to audit your cluster's performance and storage.

**Does ClickHouse (Vector Search) work with my self-hosted cluster?**
Yes, it works with both ClickHouse Cloud and self-hosted instances. You just need to provide your URL, username, and password to get started.

**Can I see my table schemas using ClickHouse (Vector Search)?**
Yes, you can ask your agent to describe any table. It will pull the column types and properties so you know exactly how your data is structured.

**Is ClickHouse (Vector Search) good for real-time analytics?**
It's built for high-performance data. Because it connects to ClickHouse, your agent can perform fast queries on large datasets for real-time reporting.

**Can my agent perform high-speed vector similarity searches?**
Yes. Provide the database, table, and the vector embedding array in JSON format. The agent uses ClickHouse's native distance functions (cosine or L2) to return the closest matches, leveraging ClickHouse's industry-leading OLAP performance.

**Can I execute arbitrary SQL commands directly through the agent?**
Absolutely. The 'execute_sql' tool allows you to push any valid ClickHouse SQL (DML, DDL, or SELECT) to your cluster. This is perfect for managing tables, updating records, or generating custom analytical reports on the fly.

**How do I check if my ClickHouse instance supports HNSW indices?**
Ask your agent to get the version details. The agent checks your ClickHouse build and identifies exactly which capability branches are active, confirming if advanced vector features like HNSW support are available in your runtime environment.