MCP Directory

How to add Ref MCP to Windsurf

Token-efficient documentation search and reading for coding agents across public and private docs. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Ref MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Ref MCP's tools become available to Cascade.

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 Windsurf

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

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Ref MCP config there under the "mcpServers" key and restart the client.

Is Ref MCP safe to use with Windsurf?

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