Ref

Claude Code

1. Run this in a terminal, in your project folder:

claude mcp add --transport http ref-tools https://api.ref.tools/mcp --header "X-Ref-Api-Key: <YOUR_API_KEY>"

1. Replace the placeholder with your key before you run it, then check it with /mcp inside Claude Code.

Add --scope user to make it available in every project, not just this one.

Claude Desktop

1. Custom connectors can’t send this server’s key header, so use the mcp-remote bridge. Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "ref-tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ref.tools/mcp",
        "--header",
        "X-Ref-Api-Key: <YOUR_API_KEY>"
      ]
    }
  }
}

1. Replace the placeholder with your key and restart Claude Desktop.

The bridge needs Node.js on your computer.

Cursor

Add to Cursor (opens in a new tab)

Or add it by hand to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project):

{
  "mcpServers": {
    "ref-tools": {
      "url": "https://api.ref.tools/mcp",
      "headers": {
        "X-Ref-Api-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

VS Code

Add it to .vscode/mcp.json. VS Code asks for the key the first time and stores it securely:

{
  "servers": {
    "ref-tools": {
      "type": "http",
      "url": "https://api.ref.tools/mcp",
      "headers": {
        "X-Ref-Api-Key": "${input:x-ref-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "x-ref-api-key",
      "description": "X-Ref-Api-Key",
      "password": true
    }
  ]
}

Devin Desktop

1. Add it to ~/.config/devin/mcp_config.json (macOS and Linux) or %APPDATA%\devin\mcp_config.json (Windows):

{
  "mcpServers": {
    "ref-tools": {
      "serverUrl": "https://api.ref.tools/mcp",
      "headers": {
        "X-Ref-Api-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

1. Refresh the MCP server list in Cascade.

Devin Desktop is the new name for Windsurf. It reads serverUrl (or url) for remote servers.

Codex

codex mcp add ref-tools --url https://api.ref.tools/mcp

Or edit ~/.codex/config.toml directly:

[mcp_servers.ref-tools]
url = "https://api.ref.tools/mcp"
env_http_headers = { "X-Ref-Api-Key" = "X_REF_API_KEY" }

Codex reads the header values from the environment variables named in env_http_headers.

Gemini CLI

gemini mcp add --transport http --header "X-Ref-Api-Key: <YOUR_API_KEY>" ref-tools https://api.ref.tools/mcp

This adds it to the current project. Add -s user to use it everywhere.

Any client

Most clients accept this shape. Some name the URL field differently: serverUrl in Devin Desktop, httpUrl in Gemini CLI’s settings file.

{
  "mcpServers": {
    "ref-tools": {
      "type": "http",
      "url": "https://api.ref.tools/mcp",
      "headers": {
        "X-Ref-Api-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

Zed puts servers under context_servers in its settings. Cline needs "type": "streamableHttp", or it assumes SSE.

Client only starts local servers? Bridge it with npx -y mcp-remote https://api.ref.tools/mcp.

README badge

[![Ref on mcp.tc](https://mcp.tc/i/ref-tools/badge.svg)](https://mcp.tc/i/ref-tools)

<a href="https://mcp.tc/i/ref-tools"><img src="https://mcp.tc/i/ref-tools/badge.svg" alt="Ref on mcp.tc" height="20"></a>

It follows the reader’s light or dark mode. Add ?theme=light or ?theme=dark to fix it, or ?style=compact to show the mark without the word.

Website card

<script src="https://mcp.tc/w/ref-tools.js" async></script>

The card appears where the tag is. Add data-theme="dark" or data-size="compact" to the tag to change it. The file holds everything it needs, so it makes no other requests and sets no cookies.

iframe

<iframe src="https://mcp.tc/embed/ref-tools" title="Ref on mcp.tc" width="420" height="200" loading="lazy" allow="clipboard-write" style="border:0;border-radius:8px;max-width:100%"></iframe>

Use it on pages that don’t allow scripts. Add ?theme=light or ?theme=dark to the address to fix the colors.

JSON

The listing as data for your own pages and tools: name, tagline, the server’s own URL, tools and the “Add to” links. Any site can read it (CORS is open).

https://mcp.tc/i/ref-tools.json

What each field means