Ref MCP
Search and read technical documentation for coding agents with less irrelevant context.
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.
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 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.
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.