Ref MCP Server: Up-to-date Docs Search for Coding Agents
Lets Claude, Cursor and other coding assistants look up current documentation for libraries and APIs, and read the right page without flooding the chat.
Ref is a documentation search service made by the Ref team, who also publish this server. The server here runs on your computer and passes your searches and page requests to Ref's service, so it needs a Ref API key from ref.tools.
The README recommends Ref's hosted endpoint over this local server, which it calls the legacy route. The hosted endpoint takes the key in its address or in a header, so follow the README for that route.
Good for
- Developers whose assistant guesses at outdated library or API behavior
- Teams who want the assistant to search their own private repos and PDFs as docs
- People who pay per token and want smaller doc lookups
Works in
12 should work
Tap an app to see how to set it up and any known problems.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Client does not support this transport.
Client does not support this transport.
Install ref-tools MCP
Claude Code
- 1
Copy this prompt.
Add the ref-tools MCP server to Claude Code. Run this command: claude mcp add ref-tools -e REF_API_KEY=<REF_API_KEY> -- npx -y ref-tools-mcp Ask me for REF_API_KEY and only put the values in that config, nowhere else. Then check that it loaded and tell me if I need to sign in or restart.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
Requires Node.js.
Ref's README recommends the hosted Streamable HTTP endpoint and calls the stdio server (npx) the legacy option. Both need a Ref API key from ref.tools. The README shows the hosted form as "type": "http", "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"; the config for this client is our adaptation of it. The key sits in the URL, so it can end up in logs, shell history and screenshots. The stdio route keeps it in an environment variable instead.
Built from the package data we hold. Not yet tested by us.
Tools
Searches public docs, and your private docs on request
Sends a question to the Ref service and gets back links to the most relevant documentation pages. Repeated searches in one session skip results you already saw. It searches public docs by default and your uploaded repos and PDFs when you ask for private sources.
Try: “Search the docs for how to post a comment with the Figma REST API.”
Network ·
ref_search_documentationReads one docs page as short markdown
Fetches a page through Ref and returns it as markdown. Ref trims it to the parts that match what the session has been searching for, rather than the whole page.
Try: “Read the n8n Merge node page that came up in that search.”
Network ·
ref_read_url
Read from the source code
Permissions
medium risk · 3 things to watch
Medium risk
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only modeHow to turn it on
Watch out for
The hosted route puts your API key in the URL
Ref's README recommends the hosted endpoint https://api.ref.tools/mcp?apiKey=YOUR_API_KEY. A key in a URL can end up in client logs, history and screenshots. The stdio route keeps it in the REF_API_KEY environment variable. github.com
Your searches and URLs go to Ref's service
Search text and page URLs are sent to api.ref.tools. Do not put secrets or private code in a query. github.com
Private docs are searchable if you upload them
The tool can search repos and PDFs you have uploaded to your Ref account when asked for private sources. Upload only what you want the assistant to see. github.com
Security advisories
No published security advisories as of Nov 1, 2026.
Technical details
| Turning on read-only | Both tools are marked read-only in the source, so there is nothing to switch off. |
|---|---|
| Talks to | api.ref.tools, which receives your search text, the page URLs you read, and your API key |
| Sign-in and keys | The Ref API key goes in the REF_API_KEY environment variable of your client config (stdio route) or in the apiKey query parameter of the hosted URL. Either way it is stored in plain text in that config file. |
Questions
Is the Ref MCP server official?
Yes. It is published by Ref (the ref-tools GitHub organization), the company behind the ref.tools documentation search service it connects to.
Does it need an API key?
Yes. The server stops with an authorization error without a Ref API key. The README says to sign up at ref.tools to get one; check the site for plans and limits.
Does it run locally or in the cloud?
The server in this repo runs on your computer, but the search and page reading happen on Ref's service. Your queries and the URLs you read are sent there.
What is the difference between the hosted and the local server?
The hosted server is the one Ref recommends; this repo holds the legacy stdio server. Both reach the same Ref service and need the same API key. The install box shows both routes for most clients. The hosted route puts the key in the URL, so keep that config file private.
Can it change or delete anything?
No. Both tools are marked read-only in the source and only search and read pages.
Can it search my private documentation?
Yes. Repos and PDFs uploaded to your Ref account can be searched when the assistant asks for private sources. Public docs are the default.
Which clients does it work with?
Any client that can run a local command, such as Claude Code, Claude Desktop and Cursor. The README also describes a mode with different tool names for OpenAI deep research.
Information
updated Nov 2, 2026
- Publisher
- Official
- Package
ref-tools-mcp- Registry
- npm
- Endpoint
https://api.ref.tools/mcp- Transport
- stdio
- Auth
- API key
- Version
- 3.0.1
- License
- MIT
- Last commit
- Oct 24, 2026
- Listed in
- Official MCP registry
Sources
Docs, issue trackers and discussions this page is built from. Issues, quotes and findings above link to their own source.
Show all 2Hide
- Ref MCP README · github.com
- Ref MCP server source · github.com