What Changes When Vector Search Becomes an MCP Tool
When an MCP server sits between an agent and a vector database instead of the agent calling an SDK directly, the call shape collapses into a single tools/call request. Only the interface gets simpler, though — index query logic, filter combinations, and error handling all move into the server's schema design. The Model Context Protocol spec defines just two messages for this: tools/list to discover tools (paginated via a cursor) and tools/call to invoke one. The parameter tuning that used to shape search quality is now a matter of inputSchema field design.
Error handling splits as well. MCP separates protocol errors — an unknown tool name, invalid arguments — from tool execution errors, where the request was valid but failed at runtime. The latter comes back inside the result with isError: true. Apply the same retry policy to both and you either abort a call that should have been retried, or retry a permanent failure forever.
Where Vectorize's Limits Drive Tool Schema Design
Running Cloudflare Vectorize as the backend means its query limits feed straight into schema design. topK tops out at 100, but requesting returnValues or returnMetadata: "all" caps it at 50 — a limit raised from 20 in March 2026. Metadata filters are capped at 10 per index, and each vector carries at most 10KiB of metadata. Expose filter fields as raw tool parameters without accounting for this, and you get filter keys that silently get ignored, or a new filter that requires a full index rebuild because the 10-index budget is already spent.
From Design to Operations: A Vectorize MCP Tool Checklist
(a) Planning starts by fixing target numbers: p95 tool-call latency under 800ms, a default topK of 10-20 to keep payloads light, and a schema-validation failure rate under 1% of all calls. Returning only the fields callers actually need instead of returnMetadata: all avoids the 50-item ceiling while keeping payloads small.
Don't port a free-text search box into the schema as-is. Expose only query, topK (server-clamped at 50), namespace, and an enumerated set of allowed metadata filter keys — lock returnValues and returnMetadata to false by default. Split single-record lookups into a separate fetch-by-id tool so broad search and point lookups don't share the same limit budget.
Failures fall into four recurring patterns. First, leaving the query field as unstructured free text lets unfiltered broad queries get embedded as-is, repeatedly landing near the topK ceiling. Second, defaulting to returnMetadata: all means responses hit the topK-50 cap often and get truncated without warning. Third, burning through the 10-metadata-index budget with no plan means adding one more filter later forces a full index rebuild. Fourth, treating protocol errors and tool execution errors with the same retry logic means permanent failures — like an unknown tool name — get retried with exponential backoff anyway.
Branch recovery by error type. Execution errors that come back as isError: true get up to 3 retries with exponential backoff; protocol errors abort immediately and escalate to a human. Requests with no filter get narrowed to a default namespace server-side, and a topK request over the ceiling gets clamped to the max instead of rejected, so the call still succeeds.
Before shipping, test boundary scenarios tool-by-tool: empty results, a mistyped filter key, a topK-100 request, and an insert that exceeds the 10KiB metadata cap. Log tool name, query hash, applied filters, topK, latency, and the isError flag as required fields so you can trace which combination hits a ceiling straight from the dashboard. Storing raw user identifiers or emails in metadata leaks PII into search results, so hash or reference-ID substitution belongs in the indexing pipeline before anything gets written.
Every week, roll up the top failure types and tally which filter combinations hit ceilings most often, keeping schema-change history separate from index-data-refresh history. That separation means you can tell immediately whether a quality drop came from a tool definition change or an embedding refresh, instead of guessing what to roll back.
Takeaways at a Glance
The moment search gets wrapped in a single MCP tool, quality stops being about the indexing algorithm and starts being about inputSchema and limit design. Put topK clamping, error-type separation, and metadata masking on the pre-launch checklist, and the tool interface stays stable even when Vectorize's own ceilings change.
References
Metadata filtering — Cloudflare Vectorize docs
Return up to 50 query results with values or metadata — Cloudflare changelog