MCP Directory

How to add Ref MCP to Claude Desktop

Token-efficient documentation search and reading for coding agents across public and private docs. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 1.1k★ · stdio · apikey

Claude Desktop config for Ref MCP

npx ref-tools-mcp@latest
{
  "mcpServers": {
    "ref-mcp": {
      "command": "npx",
      "args": [
        "ref-tools-mcp@latest"
      ],
      "env": {
        "REF_API_KEY": "<sign up to get an api key>"
      }
    }
  }
}

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the Ref MCP config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm Ref MCP's tools appear under the 🔌 tools menu.

Before you start

  • Node.js (for running via npx)
  • A Ref API key (REF_API_KEY) from ref.tools

What Ref MCP can do in Claude Desktop

ref_search_documentation

A 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_url

Fetches 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.

Security

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Ref MCP config there under the "mcpServers" key and restart the client.

Is Ref MCP safe to use with Claude Desktop?

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.

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.

View repo Full Ref MCP page