How MCP Toolbox turns agent text into ClickHouse vectors

MCP Toolbox for Databases is Google's Apache 2.0 Model Context Protocol server, originally released as genai-toolbox before MCP existed and shipped as a single Go binary that sits between AI agents and databases. The concrete change for ClickHouse users is the embeddedBy mechanism: declare a Gemini embedding model in tools.yaml, mark a tool parameter as embeddedBy that model, and Toolbox handles the text-to-vector conversion on both insert and search. The agent sends plain text and gets ranked rows back; no vector format, escape logic or embedding-service code appears in the agent's context or in application code. The article's end-to-end demo was run against Toolbox 1.9.0 against a ClickHouse Cloud 26.4.1 service, which is the version pair the integration is documented against.

Adoption is configuration rather than code: install via Homebrew, a curl-downloaded binary, Docker or npx, drop in a tools.yaml that defines a ClickHouse source plus an embeddingModel and a clickhouse-sql tool, and point an MCP client at the default 127.0.0.1:5000 loopback listener. The prebuilt --prebuilt mode exposes generic tools like execute_sql, list_tables and list_databases for development, while the YAML-defined tool pattern is positioned for production because the agent can only invoke the queries the operator wrote, with typed parameters the driver escapes on the way to the database. Connection pooling, optional authenticated tool invocation and OpenTelemetry metrics and traces ship with the server. The trade is that every agent call that needs to touch multiple databases issues separate tool calls and joins the results in its own context, since the article is explicit that each tool binds to exactly one source.

The post's main walkthrough builds an insert_doc tool that writes a (content, embedding) row to vectors.documents and a search_doc tool that ranks by cosine distance, using gemini-embedding-001 at 768 dimensions as the configured model. The supported source list is broad - PostgreSQL, MySQL, SQL Server, Oracle, MongoDB, Redis, Valkey, Elasticsearch, Neo4j, Cassandra, Snowflake, Trino, CockroachDB, TiDB, plus Google's BigQuery, AlloyDB, Cloud SQL, Spanner and Firestore - but the article only demonstrates the Gemini path for vectors, with no independent benchmark of latency, cost or recall quality. Only one feed carried the event, and it is the ClickHouse blog itself, so the picture is drawn from one tutorial rather than from third-party production reports.

The vector pipeline is bound to whichever embedding-model integrations Toolbox supports, so switching to a self-hosted embedder or another provider means waiting for a corresponding model plugin. There is also no cross-source SQL federation: an agent that needs both ClickHouse analytics and a Postgres app database issues two calls and correlates the results in its own context, not in SQL. The 127.0.0.1 default listener is loopback for good reason given database credentials, but it does mean any non-local MCP client needs an explicit tunnel or proxy, which is a deployment detail rather than a design flaw. For teams that already write and operate their own embedding services, the YAML-driven path trades flexibility for not having to maintain that code.