MCP Directory

How to add Ref MCP to Cursor

Token-efficient documentation search and reading for coding agents across public and private docs. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the Ref MCP config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of Ref MCP's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the Ref MCP config there under the "mcpServers" key and restart the client.

Is Ref MCP safe to use with Cursor?

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