Table of Contents

1. What Is the Ref MCP Server?
2. Ref vs Generic Web Search: When to Reach for Which
3. How to Install Ref MCP in 60 Seconds
4. The 6 Use Cases Where Ref Pays for Itself
5. Ref vs Perplexity vs Tavily vs Exa
6. Pricing and Free Tier
7. 5 Power-User Tips for Ref MCP
8. Frequently Asked Questions

What Is the Ref MCP Server?

Ref MCP is a Model Context Protocol server built by Ref.tools that wraps a documentation-focused search index. Where a generic web search MCP fetches and summarizes arbitrary pages, Ref is purpose-built for developer documentation: language references, framework guides, library readmes, API specs, and software docs across thousands of indexed sources.

When Claude or Cursor calls Ref's search tool, it gets back ranked passages with source attribution - usually the exact paragraph it needs, not a list of links it has to crawl. That difference matters most in coding workflows where the AI is trying to write a function against an API it does not have memorized. Ref puts the right snippet in context, saves a tool round trip, and reduces hallucination on parameters and return types.

Ref is one of a small group of MCP servers built specifically for retrieval: alongside Perplexity MCP, Tavily, Exa, and DuckDuckGo MCP. Of those, Ref is the most opinionated about docs - and the others optimize for broader web search. Most builders end up running two: Ref for docs, one of Perplexity or Tavily for general web.

Ref vs Generic Web Search: When to Reach for Which

The line between Ref and a general web search MCP is usually clear in practice:

• Use Ref when: you need API parameters, framework syntax, library install instructions, language reference details, error messages from a documented runtime, or migration guides for popular software.
• Use Perplexity / Tavily / Exa when: you need current events, news, product comparisons, opinion pieces, blog content, or queries about anything outside published documentation.

A simple heuristic: if the answer probably lives on docs.python.org, nextjs.org/docs, react.dev, or any official documentation portal, Ref will return better context. If the answer is on Hacker News, a vendor blog, or someone's personal site, reach for a general web search MCP.

For broader background on retrieval MCPs, our Exa vs Tavily vs Brave Search comparison covers the general-search side of this market in depth.

How to Install Ref MCP in 60 Seconds

Two paths: Smithery CLI (recommended) or manual config.

Option A: Install via Smithery

The fastest path. The Smithery CLI handles config generation and merges Ref into your existing MCP setup.

# Claude Desktop npx -y @smithery/cli install ref-tools/ref-tools-mcp --client claude

Claude Code
npx -y @smithery/cli install ref-tools/ref-tools-mcp --client claude-code
Cursor
npx -y @smithery/cli install ref-tools/ref-tools-mcp --client cursor
Cline / Windsurf / Continue
npx -y @smithery/cli install ref-tools/ref-tools-mcp --client <client>

Restart the client and Ref appears in the available tools list. No config editing required.

For more on Smithery's CLI flow, see our Smithery MCP Guide.

Option B: Manual Config

If you prefer to edit your MCP config by hand, add this block to your client's MCP servers config:

{   "mcpServers": {     "ref": {       "command": "npx",       "args": ["-y", "ref-tools-mcp@latest"]     }   } }

This works in Claude Desktop (claude_desktop_config.json), Claude Code (mcp.json), and Cursor's MCP settings panel. Restart the client and Ref is live.

For the free tier no API key is required. If you upgrade to a paid plan, add the API key under an env block:

{   "mcpServers": {     "ref": {       "command": "npx",       "args": ["-y", "ref-tools-mcp@latest"],       "env": { "REF_API_KEY": "ref_sk_..." }     }   } }

The 6 Use Cases Where Ref Pays for Itself

The clearest signal that Ref is worth a slot in your config: these six workflows get dramatically better with it installed.

1. Writing code against unfamiliar APIs. Ask Claude to use a library it does not have memorized (or has stale knowledge of), and watch the difference between with and without Ref. With Ref, Claude pulls the current method signature directly from the docs and writes correct code on the first try.

2. Framework migrations. Migrating from React 18 to 19, from Next.js 14 to 16, from Vue 2 to 3. Ref indexes migration guides as first-class documents and returns the right section based on your specific upgrade question.

3. Error message debugging. Paste an error message into Claude. With Ref, Claude can search docs for the exact error string and find the troubleshooting section in seconds instead of guessing.

4. Setup and install instructions. "How do I install package X with dependency Y?" - Ref pulls the install commands from the official README, which avoids both stale answers and the wrong package manager.

5. Comparing API options. "Which of these three libraries supports streaming?" - Ref can read the docs for each, find the streaming sections, and give a comparative answer grounded in current docs.

6. Internal docs (paid plan). On the paid tier, point Ref at your private documentation portal and it becomes a search interface for your company's wiki, runbooks, and API specs - inside the AI client your team already uses.

Ref vs Perplexity vs Tavily vs Exa

In practice most builders combine Ref with one general web search MCP. Our Brave Search vs Exa vs Tavily comparison is the right read for the general-search half of that pair.

Pricing and Free Tier

Ref's pricing in 2026 follows a free-first model:

• Free tier: several hundred queries per day, public docs index, no signup required to test through Smithery. Enough for most individual developers.
• Paid plan: higher rate limits, private docs indexing, team workspaces. Pricing is per-seat with a free trial.

The free tier is generous enough that you can install Ref, use it heavily, and likely never hit a limit unless you are running an agent that fires hundreds of queries an hour. For team and enterprise use, the paid plan unlocks the private-docs feature that turns Ref into a company-wide knowledge interface inside Claude Code.

5 Power-User Tips for Ref MCP

1. Pin Ref above general web search in your system prompt. If your client supports prompting around tool preference, instruct it to prefer Ref for any documentation query and fall back to web search otherwise. This avoids burning web search rate limits on questions Ref would answer better.

2. Use site-restricted queries. Ref supports filtering queries to a single doc source. Adding site:nextjs.org to a query forces results from the Next.js docs even when other sources discuss the topic. Great for migrations.

3. Combine with Sequential Thinking. Pair Ref with the Sequential Thinking MCP for multi-step research where the AI plans a query, executes it, and refines. The combination outperforms either alone for non-trivial questions.

4. Cache hot lookups in your CLAUDE.md. When Ref returns an answer you will need repeatedly (a deploy command, an env variable, a frequently-cited API), copy the result into your project's CLAUDE.md. This avoids re-querying Ref for the same answer on every session.

5. Watch the last_indexed field. Ref returns the index freshness for every result. If you are working with a framework that shipped a breaking change in the last 24 hours, Ref may still be a day behind. In that window, pair Ref with a general web search MCP to catch the very latest.

Frequently Asked Questions

What is Ref MCP?

Ref MCP is a Model Context Protocol server from Ref.tools that gives AI clients structured search across thousands of developer documentation sites. Unlike generic web search, Ref is indexed specifically for code-centric docs - language references, framework guides, API reference pages, library readmes - and returns clean, ranked snippets that paste directly into an AI assistant's context window.

Is Ref MCP free?

Yes - Ref offers a generous free tier that covers most individual usage (several hundred queries per day). Heavier usage rolls into a paid plan, but the free tier is enough for most developers running Claude Desktop, Claude Code, or Cursor day to day. There is no signup required to test it via Smithery.

How is Ref different from Perplexity MCP?

Perplexity MCP wraps the Perplexity Search API, which is a broad consumer-grade web search with summarization. Ref MCP is purpose-built for developer documentation - it indexes language references, framework docs, library readmes, and API specs, and returns ranked passages rather than a single summary. For coding tasks, Ref usually produces more directly usable context. For news, current events, or general research, Perplexity is the better fit.

Which AI clients work with Ref MCP?

All major MCP clients: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, and Zed. Ref publishes through Smithery so installation works through the standard npx @smithery/cli install ref-tools/ref-tools-mcp --client flow for every supported client.

Does Ref MCP work for my company's internal docs?

Out of the box, Ref indexes public documentation sites. Internal/private documentation is supported via the paid plan, which adds the ability to point Ref at private doc URLs (with auth) and have them indexed for your team. For purely local docs (markdown files on disk) the Filesystem MCP is usually a better fit.

How fresh is Ref's index?

Ref re-crawls major documentation sites daily. Smaller or less-popular sources may lag by a few days. The server returns a last_indexed field on each result so you can see how fresh a given doc is. For breaking framework changes (released in the last 24 hours), pair Ref with a generic web search MCP like Perplexity.

Can I use Ref MCP with the Smithery playground?

Yes - Smithery's hosted playground supports Ref. You can test queries in the browser without installing the server locally, which is useful for evaluating whether to add it to your client config. The playground link is on Ref's Smithery detail page.

What is the install command for Ref MCP in Claude Code?

Run npx -y @smithery/cli install ref-tools/ref-tools-mcp --client claude-code. The CLI writes the config block into Claude Code's mcp.json file and the server is available the next time you start Claude Code. Verify by listing MCPs with claude-code mcp list.

Last updated: June 03, 2026 · Ref index freshness and pricing verified via direct queries on 2026-06-03.