Ref MCP
Token-efficient documentation search and reading for coding agents across public and private docs.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx ref-tools-mcp@latestPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ref-mcp": {
"command": "npx",
"args": [
"ref-tools-mcp@latest"
],
"env": {
"REF_API_KEY": "<sign up to get an api key>"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Node.js (for running via npx)
- A Ref API key (REF_API_KEY) from ref.tools
About Ref MCP
A Model Context Protocol server that gives AI coding tools and agents fast, token-efficient access to documentation for APIs, services, libraries and more, including public web/GitHub docs and private repos and PDFs. It minimizes context usage by filtering duplicate search results within a session and returning only the most relevant portion of fetched pages.
Tools & capabilities (2)
ref_search_documentationA powerful search tool to check technical documentation. Great for finding facts or code snippets. Can search public documentation on the web or GitHub as well as private resources like repos and PDFs. Takes a required `query` parameter, which should be a full sentence or question.
ref_read_urlFetches content from a URL and converts it to markdown for easy reading with Ref. Powerful when used with ref_search_documentation, which returns URLs of relevant content. Takes a required `url` parameter, the URL of the webpage to read.
What this server can do
Ref MCP provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Keeping a coding agent up to date on API, library and service documentation in a fast, token-efficient way
- Finding exact facts or code snippets from technical documentation without flooding the context window
- Searching across both public web/GitHub docs and private repos and PDFs
- Reading the most relevant part of a large documentation page instead of pulling in tens of thousands of irrelevant tokens
- Acting as a documentation source for OpenAI deep research via search/fetch tools
Security notes
Requires a Ref API key (REF_API_KEY) obtained by signing up at ref.tools. Searches and reads documentation, and can access private resources like repos and PDFs that you connect; treat the API key as a secret.
Ref MCP FAQ
How do I get an API key?
Sign up at ref.tools to get a Ref API key, then set it as the REF_API_KEY environment variable in your MCP client config.
What is the difference between the stdio and streamable-http servers?
This repository is the legacy local stdio server, run via npx ref-tools-mcp. Ref also offers a streamable-http server (recommended) reachable at https://api.ref.tools/mcp with the API key passed as a query parameter or header.
How does Ref save tokens compared to normal web fetching?
Ref uses the MCP session's search history to drop less relevant sections of a page and return roughly the most relevant 5k tokens, and it filters out repeated results across similar searches in a session, avoiding the 20k+ irrelevant tokens that standard fetch scraping can pull in.
Can it be used with OpenAI deep research?
Yes. When used with an OpenAI client, Ref provides the same tools with OpenAI's required naming: ref_search_documentation becomes search(query) and ref_read_url becomes fetch(id).
Alternatives to Ref MCP
Compare all alternatives →
Official MCP reference server that fetches a URL and returns its content as clean Markdown, with chunking.
Official Firecrawl MCP server — scrape, crawl, map, search, and structured extraction for any LLM client.
Exa's neural web search and crawling MCP server — runs locally via npx or as a hosted remote endpoint.
Compare Ref MCP with: