---
title: "How MCP Toolbox turns agent text into ClickHouse vectors"
description: "MCP Toolbox for Databases addresses the gap between an AI agent’s text queries and ClickHouse’s SQL and vector interfaces by translating text into embeddings for both ingestion and search. A flat YAML configuration declares a Gemini embedding model, associates parameters with it through embeddedBy, inserts content and vectors, and ranks matches with ClickHouse’s cosineDistance function; the agent receives ranked rows without handling vectors. The post walks through installation, prebuilt ClickHouse tools, custom tools, toolsets, and an end-to-end synthetic-corpus run using Toolbox 1.9.0 and ClickHouse Cloud 26.4.1. At the demonstrated 57-row scale, search uses exact O(n) brute force because the HNSW index adds overhead, while larger datasets can use approximate search. Limitations include Gemini-only embeddings, a hardcoded SEMANTIC_SIMILARITY task type, opt-in REST endpoints, and restart-required configuration changes."
---

# How MCP Toolbox turns agent text into ClickHouse vectors

[Clickhouse](https://yomu.fyi/company/clickhouse) · Sep 7, 2026

**Type:** Tutorial

## Summary

MCP Toolbox for Databases addresses the gap between an AI agent’s text queries and ClickHouse’s SQL and vector interfaces by translating text into embeddings for both ingestion and search. A flat YAML configuration declares a Gemini embedding model, associates parameters with it through embeddedBy, inserts content and vectors, and ranks matches with ClickHouse’s cosineDistance function; the agent receives ranked rows without handling vectors. The post walks through installation, prebuilt ClickHouse tools, custom tools, toolsets, and an end-to-end synthetic-corpus run using Toolbox 1.9.0 and ClickHouse Cloud 26.4.1. At the demonstrated 57-row scale, search uses exact O(n) brute force because the HNSW index adds overhead, while larger datasets can use approximate search. Limitations include Gemini-only embeddings, a hardcoded SEMANTIC\_SIMILARITY task type, opt-in REST endpoints, and restart-required configuration changes.

## Context

AI agents that need semantic search must translate natural-language text into embeddings and connect those vectors to database queries. The post presents MCP Toolbox as a way to close that gap for ClickHouse without bespoke embedding and query-formatting code.

## Approach / What changed

A flat YAML configuration defines a ClickHouse source, a Gemini embedding model, and custom tools whose parameters use embeddedBy. An ingestion tool embeds content before insertion, while a search tool embeds the query and orders ClickHouse rows by cosineDistance. The configuration also exposes prebuilt exploration tools and groups tools into toolsets.

## Takeaways

- The embeddedBy parameter lets a hidden text parameter derive a vector from another parameter, allowing an insert statement to receive both document content and its embedding.
- The demonstrated search query orders results by cosineDistance and limits output to five rows; with 57 rows, exact O(n) brute-force scanning is used because the HNSW index adds overhead.
- MCP Toolbox hardcodes the Gemini embedding task type to SEMANTIC\_SIMILARITY, so the asymmetric RETRIEVAL\_DOCUMENT and RETRIEVAL\_QUERY pairing is unavailable through Toolbox.

**Tags:** [ClickHouse](https://yomu.fyi/topic/clickhouse), [MCP](https://yomu.fyi/topic/mcp)

- Source: [Clickhouse](https://clickhouse.com/blog/mcp-toolbox-clickhouse-vectors)
- Source URL: https://clickhouse.com/blog/mcp-toolbox-clickhouse-vectors
- Ingested by Yomu: 2026-09-07T16:00:49.272Z

[Read original post](https://clickhouse.com/blog/mcp-toolbox-clickhouse-vectors)