# Ref MCP server

> Provides token-efficient documentation search and reading capabilities for AI coding agents to minimize context rot and API costs.

- Repository: https://github.com/ref-tools/ref-tools-mcp
- Page: https://hostedmcp.org/servers/ref-tools/ref-tools-mcp-e40f3e
- Transport: stdio
- Stars: 1186
- License: MIT
- Latest version: 3.0.1

## Install

### Claude Code

```sh
claude mcp add --env 'REF_API_KEY=<YOUR_REF_API_KEY>' ref-tools-mcp-e40f3e -- npx -y ref-tools-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ref-tools-mcp-e40f3e": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "env": {
        "REF_API_KEY": "<YOUR_REF_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "ref-tools-mcp-e40f3e": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "env": {
        "REF_API_KEY": "<YOUR_REF_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ref-tools-mcp-e40f3e","type":"stdio","command":"npx","args":["-y","ref-tools-mcp"],"env":{"REF_API_KEY":"<YOUR_REF_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "ref-tools-mcp-e40f3e": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "env": {
        "REF_API_KEY": "<YOUR_REF_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add ref-tools-mcp-e40f3e --env 'REF_API_KEY=<YOUR_REF_API_KEY>' -- npx -y ref-tools-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.ref-tools-mcp-e40f3e]
command = "npx"
args = ["-y", "ref-tools-mcp"]

[mcp_servers.ref-tools-mcp-e40f3e.env]
REF_API_KEY = "<YOUR_REF_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'REF_API_KEY=<YOUR_REF_API_KEY>' ref-tools-mcp-e40f3e npx -- -y ref-tools-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "ref-tools-mcp-e40f3e": {
      "command": "npx",
      "args": [
        "-y",
        "ref-tools-mcp"
      ],
      "env": {
        "REF_API_KEY": "<YOUR_REF_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `REF_API_KEY` | yes | yes | Your API key for Ref |

## Tools (2)

- `query`
- `url`

## FAQ

### How does Ref help reduce token usage?

Ref uses the agent's session history to filter out less relevant sections of a page, returning only the most relevant 5k tokens instead of the entire page.

### Can I search for private documentation?

Yes, the search tool can be used to search for documentation from private resources like repositories and PDFs.

### What are the available tools in the Ref MCP server?

The server provides ref_search_documentation for technical documentation searches and ref_read_url to fetch and convert webpage content to markdown.

### Does Ref support OpenAI deep research?

Yes, Ref provides tool definitions compatible with OpenAI's requirements, mapping its tools to search and fetch functions.