How Ref uses MCP to build the best possible documentation search (ref.tools)

Ref announced a production MCP (Model Context Protocol) server that focuses on giving coding agents the best possible documentation search. Ref crawls public and private docs (web and GitHub), parses and chunks content into indexed snippets, and exposes two MCP tools — ref_search_documentation(query) and ref_read_url(url) — so agents like Cursor and Claude Code can find and read only the snippets they need. It also supports tool-name mapping for OpenAI deep-research clients and supplies prompt templates (search_docs and my_docs) to nudge agents to use the tools correctly. Technically, Ref leverages MCP sessions to improve efficiency and autonomy: it avoids returning duplicate results across iterative searches, pre-caches search hits to speed up fetches, and limits reads to relevant token ranges. For very large pages it reads an initial 5k tokens and then uses similarity search to extract the most useful segments, cutting token cost and reducing long-context degradation. Looking ahead Ref plans to use MCP Resources, Elicitations, and OAuth to surface team-specific stacks, ask clarifying questions for better queries, and simplify auth. The post also urges MCP client implementers to support the full spec (citing VSCode as a strong example) so servers like Ref can unlock richer agent behaviors.