ClickHouse’s MCP vector recipe exposes four production traps behind a short YAML demo

ClickHouse has published an end-to-end recipe for turning an agent’s text into vectors through Google’s MCP Toolbox for Databases. The integration is compact; the production contract is not.

In the September 7 walkthrough, a Toolbox configuration declares a Gemini embedding model and marks a typed string parameter with embeddedBy. Toolbox sends the text for embedding, binds the returned vector to parameterized SQL, and ClickHouse ranks matching rows with cosineDistance. The test used MCP Toolbox 1.9.0 and ClickHouse Cloud 26.4.1.

The pattern removes a bespoke service from the path, but the same walkthrough surfaces four controls teams should settle before exposing it to users.

1. Do not confuse exploration tools with runtime tools

Toolbox’s generic ClickHouse configuration exposes execute_sql, list_databases and list_tables. ClickHouse reports that Toolbox itself warns these prebuilt tools are intended for trusted build-time use, not runtime interactions with potentially untrusted users.

Google’s MCP Toolbox repository draws the same boundary: prebuilt tools are for build-time exploration, while its custom-tools framework is the runtime path for restricted access, structured queries, semantic search and NL2SQL. Production agents should therefore receive named, curated operations—not a general SQL executor merely because it is convenient during development.

2. Typed parameters are not server-side prepared statements

The walkthrough tested a SQL-injection-shaped string and found that the ClickHouse driver serialized and escaped it as data. That is useful, but the author also inspected system.query_log and found that the statement reached ClickHouse as an interpolated SQL string with the full vector literal included.

That distinction affects both security language and operations. Teams should say “driver-escaped typed values,” not “server-side binding,” and should budget for large query-log entries. ClickHouse also warns that Toolbox template parameters use plain string substitution, so user-controlled values belong in regular typed parameters.

3. A top-five result is not evidence of a match

In the test corpus, an unrelated dinner query still returned five rows because pure top-k search always returns k candidates. ClickHouse recommends a distance threshold, tuned against the deployment’s own data, so the tool can return no result rather than hand irrelevant context to an agent.

That makes abstention part of the evaluation target. A benchmark should include out-of-domain questions and score whether the retrieval tool returns nothing, not only whether known-answer questions place the right document first.

4. The embedding defaults impose a retrieval ceiling

For Toolbox 1.9, the walkthrough found Gemini was the only embedding provider and that SEMANTIC_SIMILARITY was hardcoded for both documents and queries. Google’s retrieval-specific pairing—RETRIEVAL_DOCUMENT for content and RETRIEVAL_QUERY for questions—could not be selected. ClickHouse’s conclusion is direct: if retrieval quality is the priority, embed outside Toolbox.

The practical rollout sequence is therefore: start with curated tools, keep untrusted input out of template parameters, measure query-log growth, add no-match cases to the benchmark, and compare the built-in embedding path with an external retrieval-tuned pipeline before committing. The YAML may be short; the acceptance test should not be.