Ref MCP: a documentation server that trims its own search results
Helping coding agents never make mistakes working with public or private libraries without wasting the context window.
At a glance
- What is it?
- Ref MCP is a Model Context Protocol server that gives coding agents two tools, ref_search_documentation and ref_read_url, and uses the session history to drop repeated hits and return roughly the most relevant 5k tokens of a page. The interesting part is the filtering, not the fetching.
- Who is it for?
- Adopt Ref MCP if your agent already burns context on documentation pages and you accept an API key and a hosted endpoint at api.ref.tools in exchange for smaller reads. Do not adopt it if you need a fully local, offline documentation index or if you cannot send your queries to a third party, since both the streamable HTTP and stdio paths require REF_API_KEY.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The context window problem Ref MCP is aimed at
A coding agent that needs to know how a library's API behaves has two bad options. It can guess from training data, which goes stale, or it can fetch documentation pages, which drags in whatever the page contains. The README's own framing is that a standard fetch() against a large documentation page can pull 20k or more tokens into context, most of it irrelevant to the question. Ref MCP exists to sit between the agent and that page.
The target user is not a human reading docs. It is an agent runtime that speaks Model Context Protocol, such as Claude Code, Cursor, or an OpenAI deep research client. The README describes the intended loop explicitly: the agent issues one or more searches, then chooses a few resources to read in more depth. Ref's job is to make both halves cheaper. The README also cites context rot research from Chroma and a cost example using Claude Opus pricing to argue that irrelevant tokens are not free. That cost arithmetic is the project's own illustration, not an independent measurement.
Two tools, and a session that remembers what it already returned
The server exposes two tools. ref_search_documentation takes a single required parameter, query, and the README says it should be a full sentence or question rather than keywords. It searches public documentation on the web and on GitHub, plus private resources such as repositories and PDFs. ref_read_url takes a required url and converts the page to markdown.
The mechanism that distinguishes Ref from a plain search-and-fetch pair is session state. The README states that Ref uses MCP sessions to track search trajectory. Two behaviours follow. First, for repeated similar searches within a session, Ref will never return repeated results, so instead of paging to the next result the agent can page and rephrase at the same time. Second, when reading a page, Ref uses the session search history to drop less relevant sections and return roughly the most relevant 5k tokens.
That second behaviour is the one worth scrutinising. The read budget is fixed at about 5k tokens regardless of how large the source page is, and the selection depends on what the agent searched for earlier in the same session. A read issued without a preceding search, or after a search that drifted off topic, has less signal to rank sections with. The README does not describe a fallback for that case.
What the token accounting in the README actually shows
The README walks through two example sessions with per-call token counts. A simple Figma query is two calls: a search for the post comment endpoint at 54 tokens, then a read of the Figma API page at 385 tokens. A harder n8n question about merge versus Code nodes runs to eight calls, including a 4,961 token read of the merge node page, a 2,310 token read about output from other nodes, and three searches in the 370 token range that look like the agent rephrasing after a weak result.
Read that second trace carefully and it undercuts a simple story about Ref making everything small. The complex session still pulled thousands of tokens, and several searches returned little. What the trace shows is an agent iterating: search, read, refine, search again. The filtering described in the README is what makes the iteration affordable, because a repeated search does not re-serve the same hits. These numbers are the project's own examples, not a benchmark, and the README does not state how the token counts were computed.
Installing it: HTTP endpoint versus the stdio server in this repo
The README offers two setup paths and is explicit that they are not equivalent. The recommended path is streamable HTTP, configured in an MCP client as an object with type set to http and a url of https://api.ref.tools/mcp?apiKey=YOUR_API_KEY. The alternative is the legacy stdio server, and the README states plainly that this repository contains the legacy stdio server. That is a real fork in the road: the code you clone here is not the code behind the recommended endpoint.
The stdio configuration uses npx with the package name and an environment variable:
"command": "npx", "args": ["ref-tools-mcp@latest"], "env": { "REF_API_KEY": "<sign up to get an api key>" }
Both paths require a key, obtained by signing up. For local development the README gives npm install, npm run dev, npm run build, and npm run watch, plus npm run inspect to test against the MCP Inspector. There is also an OpenAI deep research compatibility mode: when used with an OpenAI client, the same tools are exposed under different names, ref_search_documentation as search and ref_read_url as fetch(id). That renaming is a client-side contract, so an OpenAI integration written against search and fetch will not match the names used elsewhere.
Where Ref MCP is the wrong tool
The clearest limitation is stated in the setup section: there is no keyless or fully offline mode. Every configuration in the README carries an API key, and the recommended path points at api.ref.tools. If your constraint is that queries and the URLs your agent reads must not leave your infrastructure, this server does not satisfy it, regardless of the MIT licence on the code in this repository, because the search and ranking happen on the hosted side.
The second limitation is the fixed read budget. A roughly 5k token slice chosen by relevance to prior searches is the right default for an agent answering a narrow question. It is the wrong default for a task that needs a page read end to end, such as auditing a changelog or diffing two versions of an API reference. Nothing in the README suggests a parameter to raise the budget or disable section dropping.
The third is the session dependency itself. Filtering repeated results and ranking sections both rely on search history held for the MCP session. Long-lived or stateless client setups that do not preserve session identity will not get the behaviour the README describes, and the README does not document how sessions are keyed or how long they persist.
Compared with letting the agent fetch pages directly
The obvious alternative is the one the README argues against: give the agent an ordinary web fetch or search tool and let it read whole pages. The difference is where selection happens. With a plain fetch, the agent receives the page and the model decides what matters by reading all of it, so the irrelevant sections are already in context and already billed. With Ref, selection happens before the content reaches the model, using the session's search trajectory as the ranking signal, and the model sees a truncated slice.
That trade is not free in either direction. Pre-filtering can drop the paragraph the agent needed, and the agent has no way to notice the omission because it never saw the page. Post-filtering cannot drop anything, but it pays for every token. Ref's design assumes the second failure is more common and more expensive than the first. The README's cost example, roughly nine cents per step for 6k tokens of noise on Opus, is the argument for that assumption. Whether it holds for your workload depends on how often your agent's questions need a full page rather than a section.
Maintenance, versioning and what the MIT licence does not cover
The repository is TypeScript, MIT licensed, not archived, with a last push in June 2026. No releases were retrieved, so there is no changelog to read and no tagged version to reason about. The stdio configuration in the README uses ref-tools-mcp@latest, which means every install resolves to whatever is current at that moment. For a tool that sits in an agent's tool loop, that is a moving target; pinning an exact version in the args array is the only way to make a working setup reproducible, and the README does not recommend pinning.
On licensing: MIT covers the code in this repository, which the README identifies as the legacy stdio server. It says nothing about the hosted service at api.ref.tools, the API key, or the terms attached to the private repository and PDF search features. Those are separate from the source licence, and the README does not describe them. If you need to know what happens to documents you point the agent at, that is a question for the service, not for the LICENSE file.
Editorial conclusion
Adopt Ref MCP if your agent already burns context on documentation pages and you accept an API key and a hosted endpoint at api.ref.tools in exchange for smaller reads. Do not adopt it if you need a fully local, offline documentation index or if you cannot send your queries to a third party, since both the streamable HTTP and stdio paths require REF_API_KEY. Before wiring it into a workflow, verify which server you are actually installing: the README says this repository contains the legacy stdio server while the streamable HTTP endpoint is the recommended path, and no releases were retrieved for this repository, so pin the npm version you test rather than trusting ref-tools-mcp@latest.
Community notes