# Ref MCP server

> Search public and private documentation and read pages as markdown while using as few tokens as possible.

- Listing: https://mcp.tc/i/ref-tools
- Connect: use the server's own URL `https://api.ref.tools/mcp` (with your API key); clients connect to it directly. The listing link is a page, not an MCP endpoint.
- Type: remote (Streamable HTTP)
- Auth: API key
- Category: [Docs & Knowledge](https://mcp.tc/c/docs-knowledge)
- Vendor: Ref
- Homepage: <https://docs.ref.tools/context/getting-started/intro>
- Repository: <https://github.com/ref-tools/ref-tools-mcp>
- Package: npm `ref-tools-mcp`

## About

Ref gives coding agents access to documentation for APIs, services and libraries. It searches public docs on the web and GitHub, plus private sources such as repos and PDFs, and reads a URL as markdown. It uses the MCP session's search history to skip repeated results and return only the most relevant part of a page, about 5k tokens.

A hosted streamable HTTP endpoint is available at https://api.ref.tools/mcp, which takes an API key in the X-Ref-Api-Key header or an apiKey query parameter. A local stdio package, ref-tools-mcp, runs with npx and reads REF\_API\_KEY. The source is MIT licensed.

## What it can do

- Search public documentation on the web and GitHub
- Search private repos and PDFs
- Read any URL converted to markdown
- Skip repeated results across similar searches in a session
- Return the most relevant part of a long page
- Expose search and fetch tool names for OpenAI deep research

## Example prompts

- "Find the Figma REST API endpoint for posting a comment."
- "Search the docs for how the n8n Merge node handles multiple inputs."
- "Read this documentation URL and summarize the auth section."
- "Look up the correct usage of this library's config options in its docs."

## Install

### Claude Code

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

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

2. 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:

`claude_desktop_config.json`:

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

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

The bridge needs Node.js on your computer.

### Cursor

[Add to Cursor](<https://cursor.com/install-mcp?name=ref-tools&config=eyJ1cmwiOiJodHRwczovL2FwaS5yZWYudG9vbHMvbWNwIiwiaGVhZGVycyI6eyJYLVJlZi1BcGktS2V5IjoiPFlPVVJfQVBJX0tFWT4ifX0%3D>) (opens Cursor)

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

`mcp.json`:

```json
{
  "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:

`.vscode/mcp.json`:

```json
{
  "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):

`mcp_config.json`:

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

2. Refresh the MCP server list in Cascade.

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

### Codex

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

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

`config.toml`:

```toml
[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

```bash
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.

```json
{
  "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`.

## Details

- Server version: 3.0.1
- Last checked: 2026-10-03 (reachable, asks for credentials)
- Listed: 2026-10-03
- Updated: 2026-10-03

---
Source: https://mcp.tc/i/ref-tools (mcp.tc is an independent directory, not affiliated with this server's publisher). Corrections: https://mcp.tc/report