How MCP Toolbox turns agent text into ClickHouse vectors

Google's open-source MCP Toolbox for Databases, version 1.9.0, now natively supports ClickHouse, enabling AI agents to perform semantic search by automatically converting text queries into vectors using a Gemini embedding model, eliminating the need for custom embedding code. The tool, which also supports PostgreSQL, MySQL, and other databases, allows developers to define parameterized SQL tools in YAML, with features like connection pooling and OpenTelemetry metrics.

If you've built an AI agent that needs semantic search, you've probably hit the same awkward gap everyone hits: your LLM speaks text, your database speaks SQL and vectors, and something in the middle has to do the translation. Usually that something ends up being bespoke application code or tools you write and maintain - accept a query string, call an embedding API, format the vector, splice it into SQL, hope you escaped everything correctly. MCP Toolbox for Databases https://github.com/googleapis/mcp-toolbox by Google closes that gap natively, and it works with ClickHouse out of the box. You declare a Gemini embedding model in YAML, mark a tool parameter as embeddedBy that model, and Toolbox handles the entire text → vector → search pipeline transparently. The agent never sees a vector. It sends "how do I configure TTL on a table?" and gets back ranked rows. In this post I'll cover what MCP Toolbox is, how to install and set it up, how to use its prebuilt ClickHouse tools, and then the main event: building an ingestion tool that embeds on insert and a search tool that embeds the query and ranks by cosine distance - with no embedding service of your own to write or maintain. Then we'll load a synthetic corpus through it and look at what actually comes back. Want to try it out? Give this post to your coding agent and let it follow the steps and set everything up for you. Everything below was run end to end against Toolbox 1.9.0 and a ClickHouse Cloud 26.4.1 service, the stable releases at the time of writing. What is MCP Toolbox? MCP Toolbox for Databases is Google's open-source Apache 2.0 Model Context Protocol server, originally released as genai-toolbox before MCP existed and since renamed. It's a single Go binary that sits between AI agents and your databases, and it serves two distinct purposes: 1. A ready-to-use MCP server. Point it at databases such as ClickHouse and Postgres with a --prebuilt flag and any MCP client - Claude Code, Gemini CLI, Codex, your IDE - instantly gets generic tools like execute sql and list tables . Great for exploration and development. 2. A custom tools framework. Define curated, parameterized SQL statements in YAML and expose those as tools instead of raw SQL access. This is a great pattern for production as the agent can only invoke the queries you wrote, passing typed parameters that the driver escapes on its way to the database. Alongside ClickHouse it supports PostgreSQL, MySQL, SQL Server, Oracle, MongoDB, Redis, Valkey, Elasticsearch, Neo4j, Cassandra, Snowflake, Trino, CockroachDB, TiDB, and the Google Cloud fleet AlloyDB, BigQuery, Cloud SQL, Spanner, Firestore . A single tools.yaml can define sources across several of them, so one MCP endpoint can expose tools for your ClickHouse analytics and a Postgres app database side by side. That isn't federation, though - each tool binds to exactly one source, so an agent correlates the two by making two calls and joining the results in its own context, not in SQL. Under the hood you also get connection pooling, optional authenticated tool invocation, and OpenTelemetry metrics and traces for free. Installation Pick whichever fits your setup: 1 Homebrew macOS / Linux 2brew install mcp-toolbox 3 4 Or grab the binary directly see the releases page for versions/platforms 5export VERSION=1.9.0 6curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox 7chmod +x toolbox 8 9 Or Docker 10docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION 11 12 Or zero-install via npx convenient, but not the fastest startup 13npx @toolbox-sdk/server --config tools.yaml Verify with toolbox --version . The server listens on 127.0.0.1:5000 by default - loopback, not all interfaces, which is the right default for a process holding database credentials. Here is an example tools.yaml 1kind: source 2name: my-clickhouse 3type: clickhouse 4host: ${CLICKHOUSE HOST} 5port: ${CLICKHOUSE PORT} 6database: ${CLICKHOUSE DATABASE} 7user: ${CLICKHOUSE USER} 8password: ${CLICKHOUSE PASSWORD} 9protocol: ${CLICKHOUSE PROTOCOL} 10secure: true 11 12--- 13kind: tool 14name: execute sql 15type: clickhouse-execute-sql 16source: my-clickhouse 17description: Execute a SQL query against ClickHouse and return the rows. 18 19--- 20kind: tool 21name: list databases 22type: clickhouse-list-databases 23source: my-clickhouse 24description: List all databases in ClickHouse. 25 26--- 27kind: tool 28name: list tables 29type: clickhouse-list-tables 30source: my-clickhouse 31description: List the tables in a ClickHouse database. 32 33--- 34kind: embeddingModel 35name: gemini-embedder 36type: gemini 37model: gemini-embedding-001 38project: ${GOOGLE CLOUD PROJECT} 39location: ${GOOGLE CLOUD LOCATION} 40dimension: 768 41 42--- 43kind: tool 44name: insert doc 45type: clickhouse-sql 46source: my-clickhouse 47description: Indexes a new document and its vector embedding. 48statement: | 49 INSERT INTO vectors.documents content, embedding VALUES ?, ? 50parameters: 51 - name: content 52 type: string 53 description: The text content to store. 54 - name: text to embed 55 type: string 56 description: Hidden copy of content, embedded as a vector. 57 valueFromParam: content 58 embeddedBy: gemini-embedder 59 60--- 61kind: tool 62name: search docs 63type: clickhouse-sql 64source: my-clickhouse 65description: Finds the most semantically similar documents to a query. 66statement: | 67 SELECT content, cosineDistance embedding, ? AS distance 68 FROM vectors.documents 69 ORDER BY distance ASC 70 LIMIT 5 71parameters: 72 - name: query 73 type: string 74 description: The natural-language search query. 75 embeddedBy: gemini-embedder 76 77--- 78kind: toolset 79name: semantic search 80tools: 81 - insert doc 82 - search docs 83 84--- 85kind: toolset 86name: clickhouse explore 87tools: 88 - execute sql 89 - list databases 90 - list tables An FYI before you write any YAML: 1.9 prefers a flat config format . Each resource is its own YAML document with kind , name , and type keys, separated by --- . Older examples on the internet use a nested format sources: → my-clickhouse: → … where kind carries the type. That older shape still parses and runs fine in 1.9 I kept a nested config around and it executed happily so nothing is broken if you have one. toolbox migrate converts it when you want the new shape, and all the examples below use it. Quick start: prebuilt ClickHouse tools You can use Toolbox as a generic ClickHouse MCP server, similar to connecting it to mcp-clickhouse https://github.com/clickhouse/mcp-clickhouse or the ClickHouse Cloud MCP server https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp . Add this to your MCP client config e.g. .mcp.json for Claude Code or claude desktop config.json for Claude Desktop : 1{ 2 "mcpServers": { 3 "clickhouse": { 4 "command": "npx", 5 "args": "-y", "@toolbox-sdk/server", "--prebuilt=clickhouse", "--stdio" , 6 "env": { 7 "CLICKHOUSE HOST": "your-instance.clickhouse.cloud", 8 "CLICKHOUSE PORT": "8443", 9 "CLICKHOUSE USER": "default", 10 "CLICKHOUSE PASSWORD": "…", 11 "CLICKHOUSE DATABASE": "default", 12 "CLICKHOUSE PROTOCOL": "https" 13 } 14 } 15 } 16} All six of those variables are required, and the prebuilt config fails fast and tells you exactly which one is missing, which is nicer than a connection timeout. Note that CLICKHOUSE HOST is a bare hostname: scheme and port live in CLICKHOUSE PROTOCOL and CLICKHOUSE PORT , so https://host:8443 in the host field won't work. That gives your agent three tools immediately: execute sql , list databases , and list tables . You can now ask "what's the schema of my events table?" and the agent figures it out. Toolbox is refreshingly blunt about what this mode is for, logging a warning on every start: These prebuilt configs are intended for 'build-time' use cases, where agents are helping trusted developers build things. They are not secure enough for 'run time' use cases, where the agent will be talking to potentially untrusted developers. Which is the cue for the curated tools below. Native text → vector → search ClickHouse also has strong vector search https://clickhouse.com/blog/vector-search-clickhouse-p1 support, and includes distance functions such as cosine and support for HNSW indexes. Toolbox's custom tools framework has first-class embedding models as a resource type. When a tool parameter carries an embeddedBy: <model-name hint, Toolbox intercepts the raw text at invocation time, batches it to the embedding model's API, and binds the resulting vector to the statement's ? placeholder. For ClickHouse specifically, the vector is handed to the clickhouse-go driver as a raw float32 rather than a string you assembled yourself: 1// internal/embeddingmodels/embeddingmodels.go 2// FormatVectorForClickHouse returns the raw float32 slice, which the 3// clickhouse-go driver binds natively to Array Float32 parameters. 4func FormatVectorForClickHouse vectorFloats float32 any { 5 if len vectorFloats == 0 { 6 return float32{} 7 } 8 return vectorFloats 9} That means your SQL can use ClickHouse's vector functions directly against a parameter placeholder. There are exactly two of these formatters in the codebase - one for pgvector, one for ClickHouse. Don’t be confused by the ? , it's not the same as a "prepared statement". I pulled the executed statement back out of system.query log , and the vector arrives inlined as a literal : 1query head: SELECT content, cosineDistance embedding, -0.002279004, 0.012003845, 0.0052243723, … 2query len: 10626 3param 1 present in Settings: 0 There is no server-side parameter binding here, no param settings, just a ten-kilobyte SQL string that clickhouse-go interpolated client-side. I tested some basic injection to see how this affects security, by putting x' AS a FROM system.one WHERE 1=1 UNION ALL SELECT version -- into a string parameter. It comes back as that exact text in a result column, not as executed SQL. So the guarantee is the driver serialises typed values for you and escapes them , which removes the injection class you'd create by hand-building literals. It just isn't a prepared statement. It has its downsides, too. Every embedded query writes its full text, vector included, into query log . A busy search tool will inflate that table considerably, and vectors are the least compressible thing you could put there. Step 1: The ClickHouse table We need a table to hold documents and their embeddings. A few deliberate choices here: 1CREATE DATABASE vectors; 2 3CREATE TABLE vectors.documents 4 5 id UUID DEFAULT generateUUIDv4 , 6 content String, 7 embedding Array Float32 , 8 INDEX idx embedding embedding TYPE vector similarity 'hnsw', 'cosineDistance', 768 9 10ENGINE = MergeTree 11ORDER BY id ; Notes on the schema: - Array Float32 is the canonical embedding column type in ClickHouse, and it's what Toolbox binds to. - The vector similarity skipping index gives you approximate nearest neighbor HNSW search. The third argument 768 is the vector dimension and must match the dimension you configure on the embedding model . On 26.4 both allow experimental vector similarity index and enable vector similarity index were already 1 , so no setting change was needed; on older releases you may need to enable them yourself. For small corpora up to a few million rows you can skip the index entirely - brute-force cosineDistance over a columnar Array Float32 is fast, and you can always add the index later with ALTER TABLE ... ADD INDEX . - Pick cosine and stick to it. gemini-embedding-001 output at 768 dimensions is not unit-normalized - across my corpus the L2 norms ran 0.5788 to 0.5928, averaging 0.5862. cosineDistance normalizes internally so it doesn't care, but L2Distance will rank differently and skew with magnitude, and because the index above declares 'cosineDistance' , an L2Distance query gets no index help at all. Choose one metric, declare it in the index, and use it consistently. - ORDER BY won't accelerate the vector search itself - ANN search goes through the skipping index. Choose your ORDER BY based on the metadata filters you'll combine with vector search tenant, category, date . It's effectively immutable, ALTER TABLE … MODIFY ORDER BY can only append columns, not reorder or remove them, so decide before you load data. If your search tool will always filter by, say, category , put that first: ORDER BY category, id . On ClickHouse Cloud you get the shared-storage engine substituted automatically, with the index carried through intact: 1CREATE TABLE vectors.documents 2 3 id UUID DEFAULT generateUUIDv4 , 4 content String, 5 embedding Array Float32 , 6 INDEX idx embedding embedding TYPE vector similarity 'hnsw', 'cosineDistance', 768 GRANULARITY 100000000 7 8ENGINE = SharedMergeTree '/clickhouse/tables/{uuid}/{shard}', '{replica}' 9ORDER BY id 10SETTINGS index granularity = 8192 Step 2: The Toolbox configuration Everything lives in one tools.yaml . Three kinds of resources: a source, an embedding model, and the tools. The source ClickHouse Cloud connects over HTTPS on 8443; a local instance uses HTTP on 8123: 1kind: source 2name: my-clickhouse 3type: clickhouse 4host: ${CLICKHOUSE HOST} 5port: ${CLICKHOUSE PORT} 6database: ${CLICKHOUSE DATABASE} 7user: ${CLICKHOUSE USER} 8password: ${CLICKHOUSE PASSWORD} 9protocol: ${CLICKHOUSE PROTOCOL} 10secure: true The embedding model As of 1.9, gemini is the only supported provider - there's a single gemini package under internal/embeddingmodels , and openai , ollama , bedrock and friends are all rejected at config parse time. If you need a different provider today, you're embedding outside Toolbox. There are two ways to authenticate, and the choice is implied by which fields you set. An API key from Google AI Studio: 1kind: embeddingModel 2name: gemini-embedder 3type: gemini 4model: gemini-embedding-001 5apiKey: ${GOOGLE API KEY} 6dimension: 768 Or project and location instead of apiKey , which switches it to the Vertex AI backend and picks up your Application Default Credentials: 1kind: embeddingModel 2name: gemini-embedder 3type: gemini 4model: gemini-embedding-001 5project: ${GOOGLE CLOUD PROJECT} 6location: ${GOOGLE CLOUD LOCATION} e.g. us-central1 7dimension: 768 With gcloud auth application-default login already done, that second form works with no further setup, and the server confirms which path it took on startup: 1INFO "Using Vertex AI backend for Gemini embedding" "my-project" "us-central1" 2INFO "Initialized 1 embeddingModels: gemini-embedder" The field list is short and strict: model , dimension , and then either apiKey or project + location . Plausible-looking extras useVertex , taskType , outputDimensionality are all rejected as unknown fields. You can see the reason for rejecting these fields in the source: 1// internal/embeddingmodels/gemini/gemini.go 2embedConfig := &genai.EmbedContentConfig{ 3 TaskType: "SEMANTIC SIMILARITY", 4} 5 6if m.Dimension 0 { 7 embedConfig.OutputDimensionality = genai.Ptr m.Dimension 8} First, dimension maps straight onto OutputDimensionality , which tells you the field instructs the model rather than describing it. Set dimension: 512 against the same gemini-embedding-001 and you get a 512-element vector back. So there's no model output dimension you need to look up; the only thing dimension has to agree with is the width declared in your column's vector similarity index. Because Toolbox has no idea what that is, a disagreement surfaces as a ClickHouse error on insert or search, not as a config parse failure. Get it right up front. Second, and more consequentially for a semantic search post: taskType is hardcoded to SEMANTIC SIMILARITY , which is why the config field is rejected. Google's own guidance for retrieval is asymmetric - embed your documents as RETRIEVAL DOCUMENT and your queries as RETRIEVAL QUERY , so that the two sides land in the space the model was tuned for. Toolbox gives you neither, and no override. SEMANTIC SIMILARITY optimises for "are these two texts alike?", which is a subtly different question from "does this document answer this query?", and it's the same task type on both the ingest and search paths. In practice it still works well, as the results below show. But it's a plausible contributor to the compressed distance spread you'll see there - everything landing between 0.15 and 0.30 rather than spreading out - and if you need to squeeze retrieval quality, this is the knob you'd reach for first and the one you can't currently turn. Embedding outside Toolbox is the only way to set it today. The ingestion tool Here's the clever bit. On insert you need the same text twice - once to store as String , once to embed into the vector column. Asking an LLM to repeat an identical string across two parameters is wasteful and error-prone, so Toolbox has valueFromParam : a hidden parameter that mirrors another parameter's value. It never appears in the tool manifest - the agent doesn't know it exists: 1kind: tool 2name: insert doc 3type: clickhouse-sql 4source: my-clickhouse 5description: Indexes a new document and its vector embedding. 6statement: | 7 INSERT INTO vectors.documents content, embedding VALUES ?, ? 8parameters: 9 - name: content 10 type: string 11 description: The text content to store. 12 - name: text to embed 13 type: string 14 description: Hidden copy of content, embedded as a vector. 15 valueFromParam: content 16 embeddedBy: gemini-embedder Asking the server for its tool manifest over MCP returns a single property for insert doc : 1- execute sql | params: sql 2- insert doc | params: content 3- list databases | params: none 4- list tables | params: database 5- search docs | params: query The search tool. The agent supplies plain text; Toolbox embeds it and binds the vector to the ? : 1kind: tool 2name: search docs 3type: clickhouse-sql 4source: my-clickhouse 5description: Finds the most semantically similar documents to a query. 6statement: | 7 SELECT content, cosineDistance embedding, ? AS distance 8 FROM vectors.documents 9 ORDER BY distance ASC 10 LIMIT 5 11parameters: 12 - name: query 13 type: string 14 description: The natural-language search query. 15 embeddedBy: gemini-embedder Optionally, group them into a toolset so clients can load just these two: 1kind: toolset 2name: semantic search 3tools: 4 - insert doc 5 - search docs Two constraints to remember. Only string -typed parameters can declare embeddedBy , which the config parser catches before the server will even start: 1ERROR "unable to parse config file at \"tools.yaml\": document 3: error unmarshaling 2tool \"dim probe\": … parameter type \"integer\" cannot specify 'embeddedBy'" The referenced embedding model must also be defined in the same configuration - but that one is not checked at parse time. A tool pointing at a model that doesn't exist loads happily and fails on first use, which is a much worse place to find out: 1ERROR "error embedding parameters: embedding model does not exist: does-not-exist" Step 3: Run it 1./toolbox --config tools.yaml listens on 127.0.0.1:5000 I usually go straight to the bundled UI at http://127.0.0.1:5000/ui add --ui when you start the server to eyeball what loaded. But before wiring up a client at all, you can exercise a tool straight from the shell: 1toolbox invoke search docs '{"query":"making queries faster"}' \ 2 --config tools.yaml --log-level ERROR The --log-level ERROR matters if you're piping into jq : Toolbox writes its startup log lines to stdout alongside the JSON result, so a default-level invocation produces output that isn't valid JSON. This one-liner is the fastest way to prove your embedding credentials work before you start debugging a client integration. Loading a corpus A two-row demo doesn't tell you much about whether semantic search is working, so we can load something with enough topical spread to be falsifiable: 57 short documents across five clusters - ClickHouse internals, operations and Kubernetes, general programming, cooking, and hillwalking. Retrieval that's actually semantic should cross those cluster boundaries when the wording demands it and stay inside them when it doesn't. Ingestion goes through the insert doc tool itself, so Toolbox does all the embedding. Note that the /api/tool/<name /invoke REST endpoints are off by default in 1.9 , and hitting one without the flag returns 410 Gone with an error: 1{"status":"Gone","error":"/api native endpoints are disabled by default. Please use the standard /mcp JSON-RPC endpoint"} Start the server with --enable-api and the same request returns 200 with correctly ranked results, so the REST route is available if you want the simpler client. I went with MCP JSON-RPC instead, for two reasons: it needs no extra flag, and it's the transport your agents will use anyway, so the seeding path exercises the same code as production traffic. The whole client is about twenty lines: php 1def invoke url: str, tool: str, arguments: dict - dict: 2 """Call a tool over Toolbox's MCP JSON-RPC endpoint.""" 3 payload = { 4 "jsonrpc": "2.0", 5 "id": 1, 6 "method": "tools/call", 7 "params": {"name": tool, "arguments": arguments}, 8 } 9 request = urllib.request.Request 10 f"{url}/mcp", 11 data=json.dumps payload .encode , 12 headers={ 13 "Content-Type": "application/json", 14 "Accept": "application/json, text/event-stream", 15 }, 16 17 with urllib.request.urlopen request as response: 18 body = json.load response 19 if "error" in body: 20 raise RuntimeError body "error" "message" 21 return body "result" The Accept: application/json, text/event-stream header is what the streamable-HTTP MCP transport specifies. Toolbox 1.9 happens to answer without it too, but send it anyway - it costs nothing and it's what a spec-compliant client does. Then fan the corpus out across a small thread pool: 1with ThreadPoolExecutor max workers=8 as pool: 2 failures = failure for failure in pool.map insert, documents if failure bash 1$ python3 seed documents.py --url http://127.0.0.1:5000 2inserted 57/57 in 4.1s Four seconds for 57 documents, at concurrency 8, with an embedding round trip to Vertex AI inside every single one. Confirming what landed: 1SELECT count AS docs, any length embedding AS dims 2FROM vectors.documents 1┌─docs─┬─dims─┐ 21. │ 57 │ 768 │ 3 └──────┴──────┘ And what it costs to store, which is more interesting than it sounds. Be careful which columns you ask for, though: data uncompressed bytes covers column data only, while bytes on disk includes the secondary indices, so comparing those two directly tells you nothing. Break the index out separately: 1SELECT sum rows AS docs, 2 formatReadableSize sum data uncompressed bytes AS col uncompressed, 3 formatReadableSize sum data compressed bytes AS col compressed, 4 formatReadableSize sum secondary indices uncompressed bytes AS idx uncompressed, 5 formatReadableSize sum secondary indices compressed bytes AS idx compressed, 6 formatReadableSize sum bytes on disk AS on disk 7FROM system.parts 8WHERE database = 'vectors' AND table = 'documents' AND active 1┌─docs─┬─col uncompressed─┬─col compressed─┬─idx uncompressed─┬─idx compressed─┬─on disk────┐ 21. │ 57 │ 178.36 KiB │ 162.34 KiB │ 100.77 KiB │ 69.05 KiB │ 231.85 KiB │ 3 └──────┴──────────────────┴────────────────┴──────────────────┴────────────────┴────────────┘ Embeddings really are close to incompressible - 178.36 KiB down to 162.34 KiB is a compression ratio of 1.1x , where log and metric columns often manage 10x or more, because high-entropy floats give the codecs nothing to work with. That figure covers all three columns, but embedding is most of it; content is a few KiB of the total. And the HNSW index is 29.8% of the part at this scale, 69 KiB of the 232 KiB total, buying you nothing over a brute-force scan of 57 rows. So if you’re asking "should I add the index?" for a small corpus: not yet. Searching it Now the part that either works or doesn't. Four queries, none of which share meaningful keywords with the documents they should retrieve, top three hits each with cosine distance: "making queries faster" 10.1653 Distributed tables fan a query out to shards and merge the partial results… 20.1708 Dictionaries hold reference data in memory so joins become key lookups… 30.1715 Reading fewer columns is the single biggest lever on scan performance… "why did my container get killed" 10.1833 The OOMKilled reason on a terminated container means it exceeded its memory limit… 20.2313 Liveness probes restart a container; readiness probes only remove it from… 30.2345 A pod stuck in CrashLoopBackOff is usually failing its own startup… "staying safe in bad weather on a hill" 10.1565 Pitching a tent on a slight rise keeps you dry when overnight rain pools… 20.1667 Mountain weather can turn within an hour, so carry a shell even on a clear morning. 30.2069 Navigating with a map and compass still works when the phone battery dies… The second one is my favourite: "why did my container get killed" retrieves the OOMKilled note first, and the words killed and container aside, the query shares nothing with it - no "memory", no "limit". All three hits stay inside the twelve-document operations cluster, and none of the other 45 intrude. And then the one that's less impressive: "what should I make for dinner" 10.2853 Sourdough starter needs feeding with equal parts flour and water roughly… 20.2943 Baking is closer to chemistry than cooking, so weigh your flour rather than… 30.3030 Distributed traces show where a request spent its time; metrics tell you… The top two are in the right cluster, but a distributed tracing note has crashed the dinner party at rank three. The whole result set sits between 0.28 and 0.30, a much flatter and more distant spread than the 0.16-0.23 of the good queries. My corpus simply contains no document that answers "what should I make for dinner" - it has cooking technique , not recipes - and a pure top-k search always returns k rows whether or not any of them deserve to be there. In production you'd apply a distance threshold WHERE distance < 0.25 , tuned against your own data so the tool can return nothing rather than return noise. An agent handed three irrelevant rows will usually try to use them. Using it: MCP clients and application SDKs From an MCP client Claude Code, Gemini CLI, … Point your client at the running server over HTTP: 1{ 2 "mcpServers": { 3 "clickhouse-semantic-search": { 4 "type": "http", 5 "url": "http://127.0.0.1:5000/mcp/semantic search" 6 } 7 } 8} http://127.0.0.1:5000/mcp exposes every tool in the file; appending a toolset name scopes it to that toolset. If you'd rather not manage a long-running server, let the client own the process over stdio. This form also solves credential loading, since MCP clients don't source your shell profile: 1{ 2 "mcpServers": { 3 "clickhouse-toolbox": { 4 "command": "sh", 5 "args": 6 "-c", 7 "set -a; . \"$HOME/.config/clickhouse.env\"; set +a; exec toolbox --config /path/to/tools.yaml --stdio" 8 9 } 10 } 11} One gotcha that cost me more time than it should have, and whose real cause is not the obvious one. I added the embedding model and vector tools to tools.yaml , and an already-running Toolbox process carried on serving the old three-tool manifest. tools/list didn't include insert doc , and calling it anyway returned invalid tool name: tool with name "insert doc" does not exist - which sends you hunting for a YAML bug that isn't there. My first assumption was that hot reload had failed. It hadn't: reload works fine, for both an in-place append and an atomic replace, within a second or two. The actual culprit is that ${VAR} interpolation resolves against the running process's environment . That server had been started before I added GOOGLE CLOUD PROJECT and GOOGLE CLOUD LOCATION to my env file, so every reload attempt hit a variable it couldn't resolve, and Toolbox - reasonably - kept the last config that worked. What makes it hard to spot is the log level: 1WARN "error loading configs unable to parse config file at \"tools.yaml\": 2error parsing environment variables: environment variable not found: \"GOOGLE CLOUD PROJECT\"" That's a WARN , not an ERROR , buried in request logs, on a server you probably started in another terminal an hour ago. So: hot reload is real and you can lean on it for statement and parameter changes, but any edit that introduces a new environment variable needs a restart, because a running process can't see variables that didn't exist when it forked. Now the interaction looks like this from the agent's perspective: User: Save this note: "ClickHouse skipping indexes store metadata about granules so queries can skip blocks that definitely don't match." Agent: calls insert doc content="ClickHouse skipping indexes store…" - Toolbox copies the content into the hidden parameter, embeds it into a 768-dim vector, and binds both to the INSERT. User: What did I save about making queries faster? Agent: calls search docs query="making queries faster" - Toolbox embeds the query and ClickHouse ranks by cosine distance. The agent's tool call and the database query are both plain text and plain SQL. The vector layer is invisible. From application code For custom agents, Toolbox ships client SDKs for Python, JavaScript/TypeScript, Go, and Java, with framework adapters for LangChain/LangGraph, LlamaIndex, and Google's ADK. The core Python SDK: 1pip install toolbox-core python 1import asyncio 2from toolbox core import ToolboxClient 3 4async def main : 5 async with ToolboxClient "http://127.0.0.1:5000" as client: 6 Load the toolset and hand the tools to your agent framework… 7 tools = await client.load toolset "semantic search" 8 9 …or invoke a tool directly. The string is embedded server-side; 10 your application never touches a vector. 11 search = await client.load tool "search docs" 12 results = await search query="how do I make queries faster?" 13 print results 14 15asyncio.run main Or drop the tools straight into a LangGraph agent: python 1from toolbox langchain import ToolboxClient 2from langgraph.prebuilt import create react agent 3 4async with ToolboxClient "http://127.0.0.1:5000" as client: 5 tools = client.load toolset "semantic search" 6 agent = create react agent model, tools Either way, the embedding step stays server-side in Toolbox - swap gemini-embedding-001 for another model or change the dimension, and no application code changes. Production notes A few things worth knowing before you take this past a demo: - Batching. If a single invocation has multiple embedded parameters using the same model, Toolbox batches them into one embedding API call. But each tool invocation still embeds inline - my 57 documents meant 57 separate round trips to Vertex AI, which is fine at 4.1 seconds and very much not fine at a million rows. For bulk ingestion, embed offline and load with a proper batch pipeline tens of thousands of rows per INSERT , or async insert=1 if you must trickle . Save insert doc for agent-driven, one-at-a-time writes. - Return nothing rather than noise. As the dinner query showed, top-k always returns k rows. Add a distance threshold to search tools that an agent will act on. - Driver-escaped parameters, not prepared statements. Regular parameters are serialised and escaped by clickhouse-go from typed values, which removes the injection class - but the statement reaches the server as one interpolated string, vector literal and all, so don't describe this as server-side binding and do expect fat query log entries. Toolbox also supports templateParameters for things like table names, and those are plain string substitution with no escaping at all, so keep anything user-controlled in regular parameters. - Exact vs. approximate. cosineDistance with no index is exact and O n ; the vector similarity HNSW index makes it approximate and fast. At 57 rows the index is 29.8% of the part and earns nothing, so brute force is the whole story at this scale. Test recall on your own data before flipping to ANN. - You can't set the embedding task type. SEMANTIC SIMILARITY is hardcoded, so the asymmetric RETRIEVAL DOCUMENT / RETRIEVAL QUERY pairing Google recommends for search isn't available. If retrieval quality is the thing you're optimising, embed outside Toolbox. - Observability and auth. Toolbox emits OpenTelemetry traces including the embedding call and metrics out of the box, and tools can require authenticated invocation - worth wiring up before exposing write tools like insert doc . - Bind address and origins. The default listener is loopback-only, but --allowed-origins and --allowed-hosts both default to , and Toolbox warns about DNS-rebinding risk on every start. Set them explicitly. Wrapping up The pattern here generalizes well beyond a toy documents table: any ClickHouse table with an Array Float32 column becomes agent-searchable with about forty lines of YAML - just a declarative statement of which parameters mean text and which model turns them into vectors . And the same embeddedBy machinery drives pgvector on Postgres, the only other engine with a vector formatter in the codebase. The rough edges are mostly in the plumbing rather than the idea - Gemini is the only embedding provider, the REST endpoints need an opt-in flag, and a config that gains a new environment variable needs a restart rather than a reload. The one that isn't plumbing is the hardcoded SEMANTIC SIMILARITY task type, which puts a ceiling on retrieval quality. Given ClickHouse's brute-force vector performance on columnar data and its maturing HNSW index, this combination - MCP Toolbox for the agent boundary, ClickHouse for storage and ranking - is still one of the fastest paths I've seen from "we have text in a table" to "our agent can search it semantically." MCP Toolbox is open source Apache 2.0 at github.com/googleapis/mcp-toolbox https://github.com/googleapis/mcp-toolbox . Full docs at mcp-toolbox.dev https://mcp-toolbox.dev/documentation/introduction/ , including the ClickHouse integration https://mcp-toolbox.dev/integrations/clickhouse/source and embedding models reference https://mcp-toolbox.dev/documentation/configuration/embedding-models/ . Tested against Toolbox 1.9.0 and ClickHouse Cloud 26.4.1.