--- title: "Ref MCP Server: Token-Light Docs Search for Coding Agents" url: "https://mcpshelf.co/servers/ref" description: "Ref gives a coding assistant two tools, search docs and read a page, tuned to return only the part that matters. Hosted URL or npx setup and API key." updated: "2026-10-27" site: "MCP Shelf" --- # Ref MCP > Docs search for coding agents that returns only the part of the page that matters. Source: https://mcpshelf.co/servers/ref Markdown: https://mcpshelf.co/servers/ref.md Generated: 2026-10-27T13:22:07.460Z ## Facts - **Name:** Ref MCP - **Tagline:** Docs search for coding agents that returns only the part of the page that matters. - **Description:** Ref MCP is a documentation search server from Ref that gives coding assistants token-efficient search and reading across API, library and service docs, plus your own private docs. - **Repository:** https://github.com/ref-tools/ref-tools-mcp - **Package:** ref-tools-mcp 3.0.3 (npm) - **Install:** `claude mcp add --transport http ref "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY"` - **Server URL:** https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY - **Transport:** stdio (local), or HTTP via the hosted server - **Auth:** Needs `REF_API_KEY`, `apiKey` - **Tools exposed:** 2: `ref_search_documentation`, `ref_read_url` - **Category:** Developer tools (https://mcpshelf.co/categories/developer-tools) - **Stats:** 1.2K GitHub stars, last commit 24 Oct 2026, 0 upvotes on MCP Shelf - **Install check:** Started in our test - **Listed:** 2026-10-27 - **Page updated:** 2026-10-27 ## Full description ### What is Ref MCP? **Ref MCP is a documentation search server from Ref that gives coding assistants token-efficient search and reading across API, library and service docs, plus your own private docs.** Ref is a documentation search service with an MCP server in front. It gives the model just two tools: one searches public docs, GitHub and any private sources you have added, and the other reads a page. The reader uses what the model searched for to drop the less relevant parts of long pages, so a reply stays at a few thousand tokens instead of twenty. Within a session, repeated searches do not return pages you have already seen, which lets the model refine a query and page through results at once. The recommended way in is the hosted endpoint; this repository holds the older local stdio version. | | | | --- | --- | | Made by | Ref (ref-tools/ref-tools-mcp) | | GitHub | https://github.com/ref-tools/ref-tools-mcp | | Licence | MIT | | npm package | [ref-tools-mcp](https://www.npmjs.com/package/ref-tools-mcp) 3.0.3 (4 Nov 2025) | | GitHub stars | 1.2K | | Last commit | 24 Oct 2026 | | Tools | 2 | | Runs on | Your computer or hosted | | Install check | Started in our test | | Category | [Developer tools](https://mcpshelf.co/categories/developer-tools) | | Setup checked | 27 Oct 2026 | | Page updated | 27 Oct 2026 | **Our check:** We ran this exact config on 27 Oct 2026: it started and answered with 2 tools. #### MCP Shelf take > We started Ref on our own test machine on 27 Oct 2026 and it answered with 2 tools. Both only read, so it cannot change anything on its own. Every tool comes with a useful description, all of them say whether they change things, and the tool list costs about 100 tokens of context before you ask a thing. It sits 21st of 21 in its category on our shelf by GitHub stars (1.2K). — MCP Shelf tests (numbers from our own runs), tested on 27 Oct 2026 ### What tools does Ref MCP have? We listed 2 tools on 27 Oct 2026. Every one of them only reads. | Tool | Kind | What it is for | | --- | --- | --- | | `ref_search_documentation` | reads | Searches public docs, GitHub and your private sources. Takes a full question. | | `ref_read_url` | reads | Reads a page from the results as Markdown, trimmed to the most relevant part. | #### How clearly it describes its tools 2 of 2 tools have a description and 2 of 2 say whether they change things. The tool list takes at least ~100 tokens of context. Every tool says whether it only reads or can change things, so a client can ask before the risky ones. ### How do I install Ref MCP? #### What you need first - A Ref account and API key from ref.tools - Node.js, only for the local version #### Claude Code Where: Your terminal ```bash claude mcp add --transport http ref "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY" ``` This is Ref's hosted server, which Ref recommends. The npx ref-tools-mcp package in this repository is the older local version. #### Cursor Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project ```json { "mcpServers": { "ref": { "url": "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY" } } } ``` Ref's README also has one-click install buttons for Cursor, for both the hosted and the local version. #### Claude Desktop Where: Settings → Connectors → Add custom connector ``` https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY ``` Ref's hosted server, with your key in the address. The local npx version below also still works. #### VS Code Where: .vscode/mcp.json in your project ```json { "servers": { "ref": { "type": "http", "url": "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY" } } } ``` #### Windsurf Where: ~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "ref": { "serverUrl": "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY" } } } ``` #### ChatGPT Where: chatgpt.com/plugins → + → Add custom MCP server ``` https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY ``` Put your own key in the address and choose No authentication, since the key travels in the URL. Create it as a plugin and install it before using it in a chat. In ChatGPT the tools appear as search and fetch. Replace the key with your own from the Ref dashboard. With an OpenAI client the same tools appear as search and fetch. #### Remote option The hosted endpoint is the one Ref recommends. Add it to any client that takes a remote URL, with your key in the address. ``` https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY ``` Checked against the project's own install docs on 27 Oct 2026: https://github.com/ref-tools/ref-tools-mcp#readme, https://ref.tools ### How do I configure Ref MCP? | Setting | Kind | Required | What it does | | --- | --- | --- | --- | | `REF_API_KEY` | env | yes | Your Ref API key, for the local version. | | `apiKey` | config | yes | The same key as a query parameter on the hosted URL. Example: `https://api.ref.tools/mcp?apiKey=YOUR_KEY` | ### What can Ref MCP read and change? **It can read** - Public documentation and GitHub - Private repositories and PDFs you added to Ref **It can change** - Nothing. Searches count against your Ref plan. **Safer setup:** It only reads. Add private sources to Ref only if you are happy for them to be searched by every client that has your key. ### Good for - Looking up an API or SDK method without filling the context window - Searching your own private docs alongside public ones - Coding agents that do many small docs lookups per task ### Ref MCP not working? Common fixes **Unauthorised errors** Check the key in REF_API_KEY or in the hosted URL, with no spaces or quotes. **The local version seems behind the hosted one** This repository is the older stdio server. Ref recommends the hosted endpoint. **The tools have different names in an OpenAI client** That is deliberate. OpenAI clients see search and fetch instead. ### What are the alternatives to Ref MCP? | Server | What it does | Tools | Runs on | Licence | Stars | | --- | --- | --- | --- | --- | --- | | [Ref MCP](https://mcpshelf.co/servers/ref) | Docs search for coding agents that returns only the part of the page that matters. | 2 | Your computer or hosted | MIT | 1.2K | | [Desktop Commander](https://mcpshelf.co/servers/desktop-commander) | A terminal, file search and surgical file edits for your assistant. | 25 | Your computer | MIT | 10.1K | | [Serena](https://mcpshelf.co/servers/serena) | IDE-style "find symbol" and "edit symbol" for an agent, backed by language servers. | 3 (REPL) | Your computer | GPL-3.0 | 30.8K | | [Context7](https://mcpshelf.co/servers/context7) | Pulls current, version-specific library docs into the conversation. | 2 | Your computer or hosted | MIT | 63.8K | | [GitHub](https://mcpshelf.co/servers/github) | GitHub's own server for repos, issues, pull requests and Actions. | 46 | Hosted or your computer | MIT | 34K | | [MCP Inspector](https://mcpshelf.co/servers/mcp-inspector) | The official debugging UI for MCP servers. Not a server you add to a client. | Test client | Your computer | MIT / Apache-2.0 | 11.2K | ### Ref MCP FAQ #### How do I add Ref MCP to Claude Code? Get an API key from ref.tools, then run claude mcp add --transport http ref with the address https://api.ref.tools/mcp and your key as the apiKey parameter. #### How do I add Ref to Cursor? Use the install button in Ref's README, or add an entry whose url is https://api.ref.tools/mcp with your key as the apiKey parameter. Restart Cursor afterwards. #### Does Ref MCP work with ChatGPT? Yes, as a custom connector using the hosted address with your key in it, as shown in the ChatGPT tab. In OpenAI clients the two tools show up as search and fetch. #### How is Ref different from fetching pages myself? Ref returns only the part of a long page that matches the search, about 5,000 tokens at most, and it skips results already seen in the session, so less context is wasted. #### Ref vs Context7: which should I use? Both feed current docs to a coding assistant. Ref searches across docs sites and trims each page to the relevant part, and it can index your private repos and PDFs; Context7 focuses on library docs and code examples. #### Can Ref search my own docs? Yes. You can add private repositories and PDFs in your Ref account, and every client using your key can then search them. #### Should I use the hosted or local version? Ref recommends the hosted one at api.ref.tools. The npx ref-tools-mcp package is the legacy local version and can lag behind it. #### Is Ref MCP free? The server code is MIT licensed, but Ref itself is a service with its own plans, listed on ref.tools. You need an account and key either way. Full docs on GitHub: https://github.com/ref-tools/ref-tools-mcp ## Notes for agents Fetch these instead of parsing the HTML page: - llms.txt: https://mcpshelf.co/llms.txt - llms-full.txt: https://mcpshelf.co/llms-full.txt - ai.txt: https://mcpshelf.co/ai.txt - Full catalog (.md): https://mcpshelf.co/catalog.md - API spec: https://mcpshelf.co/openapi.json - MCP server: https://mcpshelf.co/mcp - MCP manifest: https://mcpshelf.co/.well-known/mcp.json - Developer docs: https://mcpshelf.co/developers MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.