Ref MCP
Search and read technical documentation for coding agents with less irrelevant context.
- Source repo
- ref-tools/ref-tools-mcp
- Stars
- ★ 1.2k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using Claude Code needs the exact Figma Comment REST API endpoint and wants to search before reading the matching documentation page.
- Not a fit if
- Teams that need fully offline or local-only data handling
- Users unwilling to sign up for a Ref API key
- Teams needing documented pricing, quotas, or SLAs
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Ref MCP is a Model Context Protocol server that gives AI coding tools access to documentation for APIs, services, and libraries. It offers a recommended Streamable HTTP service and a legacy local stdio mode. Its two documented tools, ref_search_documentation and ref_read_url, search documentation and convert selected web pages to Markdown. The server uses MCP session search history to avoid repeated results for similar searches and to return the most relevant portions of a documentation page, up to roughly 5,000 tokens. The repository also documents OpenAI deep research naming mappings for search and fetch.
A coding assistant calls ref_search_documentation(query) with a complete sentence or question to locate relevant technical documentation. It can then take a returned URL and call ref_read_url(url), which fetches that page and converts it to Markdown. When reading, Ref uses the current MCP session's search history to drop less relevant page sections and return the most relevant content. Similar repeated searches in a session do not return repeated results. In an OpenAI client, ref_search_documentation(query) is exposed as search(query), while ref_read_url(url) is exposed as fetch(id).
- A developer using Claude Code needs the exact Figma Comment REST API endpoint and wants to search before reading the matching documentation page.
- An engineer maintaining an n8n workflow needs to investigate Merge versus Code node behavior with multiple inputs across several documentation sections.
- A team connecting an MCP tool to a Streamable HTTP-capable coding environment wants its assistant to retrieve API, service, and library documentation on demand.
- A developer who prefers a local stdio MCP server wants to run the package through npx.
- An OpenAI client user running deep research needs the documented search and fetch interfaces for the same documentation retrieval flow.
How do you install or deploy this agent?
For the recommended Streamable HTTP mode, sign up for a Ref API key and configure:
"Ref": {
"type": "http",
"url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}
For local stdio mode, configure:
"Ref": {
"command": "npx",
"args": ["ref-tools-mcp@latest"],
"env": {
"REF_API_KEY": "<sign up to get an api key>"
}
}
For local repository development, run npm install, then npm run build. Use npm run watch for auto-rebuilding development.
How do you use this agent?
After configuring the MCP server, call ref_search_documentation with its required query parameter, for example: “Figma API post comment endpoint documentation”. Choose a URL from the search result and call ref_read_url with its required url parameter. When using the documented OpenAI deep research tool definitions, call search(query) and fetch(id) instead.
What are this agent's strengths and limitations?
- Uses MCP session search history to prevent duplicate results for similar searches.
- Filters less relevant sections when reading pages and targets the most relevant roughly 5,000 tokens.
- Supports both recommended Streamable HTTP delivery and legacy local stdio delivery.
- Documents explicit search/fetch name mappings for OpenAI deep research clients.
- Both documented connection modes require a Ref API key obtained by signing up.
- The repository labels the stdio server as legacy, creating a potential migration consideration for stdio adopters.
- Private repositories and PDFs are mentioned as searchable resources, but authentication, access-control, and setup details are not documented.
- The repository does not document API pricing, quotas, availability commitments, or retry behavior.
How does this agent compare with similar options?
The repository contrasts its page-reading approach with standard fetch() web scraping, which it says can bring 20,000+ tokens from a large documentation page into context. Ref says it filters sections using session search history and returns the most relevant roughly 5,000 tokens.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Ref MCP This agent | 54 · Major gaps | MCP serverFreemium | ★ 1.2k | 2d ago | TypeScript | OpenAI API |
| pg-aiguide: PostgreSQL Expertise for AI Coding | 53 · Major gaps | CLIFree | ★ 1.9k | 2d ago | Python | ChatGPT · Codex · Claude Code |
| Grounded Docs MCP Server | 78 · Good | CLIFree + model costs | ★ 1.9k | 7d ago | TypeScript | ChatGPT · Claude Code |
| Agentor Agent Framework | 56 · Major gaps | Library / SDKFree + model costs | ★ 214 | 11d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The product exposes two read-only tools for search and URL reading and describes searches over public or private documentation, supporting ordinary-use least privilege and some data-flow transparency. The README says a Ref API key is required and shows environment-variable configuration, but the sample does not explain key storage, rotation, or private-document handling in detail, so sensitive-data handling is only partial. Search calls the Ref service and the reader accepts a URL; the sample does not show confirmation for external effects, rollback, or source-ownership verification, which limits those scores.
The README describes filtering results using session search history, and the source declares stdio and HTTP support; missing API keys produce a configuration message. However, the README recommends HTTP while also describing this repository as the legacy stdio server, leaving its positioning inconsistent. The materials do not establish dependency or service availability, and failure-handling evidence is limited, so these scores remain modest.
The README targets coding agents looking up API, service, and library documentation, and lists search and read tools plus an OpenAI deep-research naming map. The source includes public and private documentation prompts, stdio/HTTP transports, and client-dependent tool names. Unsupported cases and environment requirements are not described in depth, so the audience and boundaries are useful but incomplete.
The README is organized around use, tools, setup, and development, with Cursor, stdio, development, and Inspector examples. package.json provides a stable package name and version, and the repository includes a complete MIT license. Known limitations receive little attention; no changelog is included in the materials, and maintenance responsibility is not explicit beyond name and contact clues.
The tools focus on documentation search and URL reading. The README explains deduplicating results, selecting relevant page content, and reducing context use, and includes usage examples, indicating clear practical value for coding agents. The benefit claims are mainly product statements and examples; the sample provides no measurements of correctness or savings, so value and cost-benefit scores are moderate.
Tool definitions, package version, setup configuration, and license can be cross-checked across the README, source, and manifests, providing some corroboration. Claims about token reduction and improved model performance are stated mainly in the README, without measurement methods or results in the sample. Claims and inference are not consistently separated, limiting traceability and evidential strength.
- The README both recommends HTTP and calls this repository the legacy stdio server; confirm the intended transport and server configuration before deployment.
- For private-document use, the source sample does not describe Ref-side data retention, access controls, or API-key lifecycle details.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/ref-tools-mcp)<a href="https://followagents.com/en/agents/ref-tools-mcp"><img src="https://followagents.com/badge/ref-tools-mcp.svg" alt="FARS review"></a>FAQ
Do I need credentials?
What content can it search?
Can it run locally?
What does it cost, and are there usage limits?
Thanks — we use this to improve the page.