Ref Tools MCP Server
API and library documentation access for AI agents to reduce context usage.
Data last scanned last week · Reviewed last month
Overview
Ref Tools MCP Server provides AI coding agents with targeted access to documentation for APIs, services, and libraries. It uses agentic search patterns to minimize token consumption and combat context rot, enabling models to retrieve and read only the most relevant sections of documentation during a development session. The server features session-aware tracking to prevent duplicate search results and performs selective content fetching. By analyzing search history, it extracts and returns only the most pertinent portions of a document, rather than performing standard, unoptimized web scrapes.
Our verdict
With a security score of 53/100, this project is considered high risk. The security audit is limited, as both OAuth support and authentication methods have not yet been reviewed, and the read-only mode support is unverified. Because the project is community-maintained rather than vendor-official and lacks comprehensive security vetting, it should be used with caution and primarily in isolated environments by users comfortable managing third-party code risks.
- Minimizes context usage for improved token efficiency
- Small footprint with only 3 direct dependencies
- Maintains an active development cycle with recent commits
- High risk score due to unreviewed authentication and OAuth
- Read-only capabilities have not been editorially verified
- Community-maintained rather than supported by an official vendor
Setup
{
"mcpServers": {
"ref-tools-mcp": {
"args": [
"-y",
"ref-tools-mcp"
],
"command": "npx"
}
}
}Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop. Some servers require API keys or tokens as environment variables — check the project's README and add an "env" object if needed.
- No read-only mode — running this grants full read/write access.
- No built-in authentication — anyone with access to this config can invoke every tool it exposes.
Tools
| Tool | Description | Risk |
|---|---|---|
| ref_search_documentation | A powerful search tool to check technical documentation for finding facts or code snippets. | low |
| ref_read_url | A tool that fetches content from a URL and converts it to markdown for easy reading. | low |
Compatibility
| Client | Local | Docker | Remote | Read-only |
|---|---|---|---|---|
| ChatGPT | ||||
| Claude Desktop | ||||
| Cursor | ||||
| VS Code | ||||
| Windsurf |
Frequently asked questions
›What are the available installation methods for the Ref MCP server?
You can set up the server using the recommended streamable HTTP method or the legacy stdio server method.
›Is an API key required to use the Ref MCP server?
Yes, you must sign up to obtain an API key, which is then configured via the x-ref-api-key header for HTTP or the REF_API_KEY environment variable for stdio.
›How does Ref minimize token usage during documentation lookups?
Ref tracks your search trajectory during an MCP session to filter out repeated results and automatically truncates documentation pages to include only the most relevant 5k tokens.
›What does the ref_search_documentation tool do?
It is a search tool used for finding facts or code snippets in public web documentation, GitHub repositories, or private resources like PDFs.
›What is the purpose of the ref_read_url tool?
It fetches content from a provided URL and converts it into markdown format to assist your agent in reading relevant documentation.
Badge
Maintain this server? Add the live badge to your README.