How MCP Toolbox turns agent text into ClickHouse vectors

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.

Takeaways

1. 1

   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.

2. 2

   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.

3. 3

   MCP Toolbox hardcodes the Gemini embedding task type to SEMANTIC_SIMILARITY, so the asymmetric RETRIEVAL_DOCUMENT and RETRIEVAL_QUERY pairing is unavailable through Toolbox.