An MCP server for a database is easy to start and hard to finish. The first version wraps a search endpoint and a SQL endpoint. Then the ideas arrive: infer the schema from the first batch, add an upsert, chunk files on the way in, split large uploads and resume them, add a dry run. Each one sounds reasonable, and each one turns the server into a second product with its own bugs.
Infino’s MCP server, @infino-ai/mcp-server, gives an agent 15 tools: keyword, semantic, hybrid and SQL retrieval, plus the writes it needs to build and change its own tables. This post is about the decisions behind that list, most of which were about what not to build, and about what we learned when we handed the server to an agent and watched.
One table, every kind of retrieval #
An agent asks three kinds of questions of the same data. Some need the exact term: an error code, a function name, an order id. Some need the meaning: a question worded differently from the document that answers it. Some need a count, a filter or a join. The usual answer is three systems, a full-text index, a vector store and a SQL database, with a sync job between them.
In Infino all three run on one table, and that table is a Parquet file with its search indexes inside. So the MCP server never routes between backends. infino_keyword_search, infino_semantic_search and infino_hybrid_search rank rows. infino_token_match, infino_exact_match and infino_count filter and tally them. infino_sql reads the same rows with SQL, and the engine’s search functions are callable inside it, so one statement can rank by relevance and then group or join the results. When an agent finds a passage by meaning and then asks how many rows mention the same product, it is reading the same copy of the data both times. We wrote about why that matters in You don’t need two databases for hybrid search.
The one thing we added: embeddings #
We set ourselves a rule for the server: expose what the Infino binding does natively, one tool per method, and add nothing of our own. We broke it once.
The engine is bring-your-own-vectors. It stores and searches vectors but does not make them, and an agent cannot produce an embedding by itself. So the server embeds both the documents it writes and the queries it searches, with the same local model (all-MiniLM-L6-v2, run through transformers.js). There is no embedding API key to manage, and the text never leaves the machine to be embedded. On Infino Cloud, only the resulting vector reaches the endpoint.
The same reasoning decided who picks the vector dimension. When an agent creates a table with vector: true, the server adds an embedding column sized to its own embedder, with a cosine index. The agent never types a dimension. That number belongs to whoever runs the server, and a wrong guess produces a table whose searches fail later, far from the mistake.
Writes are always on #
Early versions had a flag, INFINO_MCP_ENABLE_WRITES, and writes were off unless you set it. We removed it in September and did not add a read-only flag in its place. The teams using the server wanted their agents to build and maintain their own tables, and a switch inside the server was the wrong place to say no.
Limits still exist. They live where they belong. On Infino Cloud the API key’s capabilities decide what a connection may do: a read-scoped key is refused every write, and the tool result tells the agent it needs a key with write capability. Every tool also carries MCP annotations, readOnlyHint and destructiveHint, so the client decides when to stop and ask the person at the keyboard. Locally, point the server only at data the agent may change.
The write path is short. Create the table, then append tens of rows per call with infino_add_documents. Each call is one commit, and rows without a vector are embedded together in one batch. To replace rows, delete by key and add them again, and count the matches before any delete.
What we didn’t build #
The list of things we left out is longer than the list of tools.
No schema inference. An agent creates a table from an explicit column descriptor, and a document field that isn’t a column is an error, not a new column. Guessing types from the first batch works until the second batch disagrees.
No upsert emulation. Replacing a row is a delete by key, then an add. Emulating upsert in the server would have meant a read, a diff and two writes that are not atomic together, hidden behind one tool name that suggests they are.
No splitting, resuming or progress reporting for large uploads. A tool call carries tens of documents, nowhere near the size where a hosted append needs splitting, so that machinery would solve a problem the server cannot have. a whole corpus is a different job, and it already has tools: infino ingest in the Infino CLI, or an SDK.
No file chunking and no dry-run mode. Both are useful. Both belong in the agent or in an ingestion pipeline, not in a thin layer over a database.
Each of these would have been behavior that exists only inside the MCP server, documented nowhere else and tested against nothing else. Keeping the server to the binding’s own surface means there is one implementation of each behavior, in the engine, and the server’s job stays small: describe the tools well, embed text, and pass everything else through.
Small things that keep agents from misreading results #
Some of the most useful changes were small. Semantic search returns a distance, where lower is closer, while keyword and hybrid search return a relevance, where higher is better. An agent comparing scores across tools has no way to know that unless it is told, so every search response says which kind of score it carries, in a score_kind field.
We also stopped truncating. Earlier versions returned text snippets, which saved tokens but could cut off the part of a passage the agent needed. Hits now return full column values, and the columns argument chooses which fields come back: an id and a line range to cite, the full text, or metadata to filter on. To keep a response small, the agent asks for fewer columns or a smaller k.
Then we watched an agent use it #
Before shipping the write tools, we ran a coding agent headless against the server, allowed to use only the Infino tools, starting cold against a fresh database on Infino Cloud. It worked through four scenarios: ingest a small corpus from nothing, modify and delete rows, answer retrieval questions, and reset the data.
All four came out correct, in six to ten tool calls each, with no wasted calls. The useful part was where the agent didn’t do what we expected. Asked to find rows containing a literal word, it reached for SQL LIKE and infino_token_match rather than infino_keyword_search. Asked to reset, it deleted every row instead of dropping the table. Neither choice was wrong. Both showed us which tool descriptions weren’t steering it the way we assumed, and for an agent, the tool description is the only documentation it reads.
Try it #
The server is on npm as @infino-ai/mcp-server and on the official MCP Registry. Setup for Claude Code, Claude Desktop, Cursor and VS Code is in the MCP docs, and the source is on GitHub. To load a whole corpus rather than a few rows, start with the CLI.
One table for keyword, semantic, hybrid and SQL search, and an agent that owns it.
or run it yourself: `pip install infino` · Apache-2.0 · [quickstart →](https://infino.ai/docs/quickstart)
Deeper: [why one table beats two databases](https://infino.ai/blog/hybrid-search-one-engine/).