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
- 9d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 49/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API
- 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.
- Main limitation
- Both documented connection modes require a Ref API key obtained by signing up.
- Source review
- 49/100 · Major gaps 2 safety controls not found
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 | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Ref MCP This agent | 49 · Major gaps | ★ 1.2k | 9d ago | TypeScript | OpenAI API |
| pg-aiguide: PostgreSQL Expertise for AI Coding | 33 · Major gaps | ★ 1.8k | 15d ago | Python | ChatGPT · Codex · Claude Code |
| Grounded Docs MCP Server | 50 · Major gaps | ★ 1.8k | 2d ago | TypeScript | ChatGPT · Claude Code |
| Ori Mnemos | 80 · Good | ★ 324 | 4d ago | TypeScript | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: tools require only API key, no extra permissions; README explains data flow (search, read URL); dependencies are common (axios); external network requests exist. Deductions: no user confirmation, no rollback, no data retention policy, unverified publisher.
Evidence: README and package.json consistent, tool names consistent; dependencies are npm packages with version ranges; no error handling docs. Deductions: no failure message examples, no error handling explanation.
Evidence: clear target users (AI coding agents), scenarios (doc search, read); tool parameters clear; supports stdio and HTTP. Deductions: no environment limitations (e.g., network requirements).
Evidence: README structure clear, install notes detailed, naming stable (ref_search_documentation etc.), examples present, MIT license, version exists. Deductions: no known limitations section, no changelog, maintenance responsibility unclear.
Evidence: output is markdown, directly usable; value in reducing token consumption; cost-benefit explained (token cost). Deductions: no actual performance data.
Evidence: claims in README (e.g., token efficiency) lack external references; no tests or independent verification. Deductions: no tests, no external corroboration.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; use with caution.
- Tool makes external network requests, potentially leaking query content; be mindful of data privacy.
- No user confirmation mechanism; agent may automatically perform searches and reads.