# Ref MCP

> Lets your coding agent search public docs and your own repos and PDFs, then read just the parts of a page it needs.

Ref is a documentation search server for coding agents. Your agent searches public docs for APIs, services and libraries, plus your team's private docs, then reads only the parts of a page that matter. It writes code against the current docs without filling its context window with pages it doesn't need.

What you can do with it
- Search public documentation for libraries, frameworks and APIs while you code
- Search your private docs: GitHub repos you connect and PDF or Markdown files you upload
- Read any documentation URL as Markdown, trimmed to the sections that match your searches
- Use Ref's search_docs and my_docs prompts (type /Ref in agents that support MCP prompts)

Its two tools
- ref_search_documentation searches your indexed public and private documentation
- ref_read_url reads a URL from the results, or any web page, as Markdown

How it connects
Ref hosts the server at https://api.ref.tools/mcp. Connect without an API key and your agent starts an OAuth sign-in to Ref. Or pass the key from ref.tools/keys in an x-ref-api-key header, or as ?apiKey= on the address. Ref's own docs have setup steps for ChatGPT, Claude and more. The older local version runs with npx ref-tools-mcp@latest and a REF_API_KEY environment variable.

Good to know
- It only reads documentation; it doesn't change your code, repos or accounts.
- Each search or read uses one Ref credit. New accounts get 200 free credits that don't expire, and paid plans add monthly credits.
- Within a session, Ref doesn't repeat results it has already shown, and when it reads a long page it keeps the parts most relevant to your searches.
- Private repos are indexed through the Ref GitHub App and synced every five minutes.
- On a Ref team, you may need ?scope= with your team ID on the address; ref.tools/install shows it.
- With OpenAI clients the same tools are named search and fetch, so Ref can serve as a deep research source.

- Type: Plugin
- Made by: Ref
- Category: Developer tools
- Formats: Remote MCP
- Version: 3.0.1
- Website: https://ref.tools
- Source: https://github.com/ref-tools/ref-tools-mcp
- Page: https://pluginboard.ai/plugins/ref-tools-mcp

## Works with

- ChatGPT
- Claude
- Muse
- Grok Bot
- Gemini
- Grok
- GitHub Copilot
- Cursor
- Claude Code
- Codex
- Antigravity
- Gemini CLI
- Replit
- OpenClaw
- OpenCode
- Hermes Agent

## Install

You'll need:

- `X-Ref-Api-Key` (optional): API key for authentication

Replace each `<NAME>` placeholder with your own value.

### ChatGPT

In ChatGPT on the web: Plugins → + → Add custom MCP server, then paste https://api.ref.tools/mcp under Connection. Business and Enterprise plans; Pro can add read-only servers.

### Claude

In Claude (web or desktop): Customize → Connectors → Add custom connector, then paste https://api.ref.tools/mcp

### Muse

In Muse: In a Muse chat, ask it to create a custom connector for the MCP server at https://api.ref.tools/mcp. Then tap Connect on the card it shows and sign in, or add your key.

### Grok Bot

In Grok Bot: In a chat with your Bot, say "Add this MCP server: https://api.ref.tools/mcp". It confirms the details with you and sets it up, and the tools are ready from your next message.

### Gemini

In Gemini: At gemini.google.com: Settings → Connected Apps → Add a custom app, then paste https://api.ref.tools/mcp

### Grok

In Grok on the web: At grok.com/connectors: New Connector → Custom, then enter https://api.ref.tools/mcp and sign in if it asks.

### GitHub Copilot

Add to VS Code: vscode:mcp/install?%7B%22name%22%3A%22ref-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.ref.tools%2Fmcp%22%7D

Copilot CLI:

```shell
copilot mcp add --transport http ref-mcp https://api.ref.tools/mcp
```

### Cursor

Add to Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=ref-mcp&config=eyJ1cmwiOiJodHRwczovL2FwaS5yZWYudG9vbHMvbWNwIn0%3D

Add to .cursor/mcp.json:

```json
{
  "mcpServers": {
    "ref-mcp": {
      "url": "https://api.ref.tools/mcp"
    }
  }
}
```

### Claude Code

Run in your terminal:

```shell
claude mcp add --transport http ref-mcp https://api.ref.tools/mcp
```

### Codex

Run in your terminal:

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

### Antigravity

Add to ~/.gemini/config/mcp_config.json:

```json
{
  "mcpServers": {
    "ref-mcp": {
      "url": "https://api.ref.tools/mcp"
    }
  }
}
```

### Gemini CLI

Run in your terminal:

```shell
gemini mcp add --transport http ref-mcp https://api.ref.tools/mcp
```

### Replit

In Replit: At replit.com/integrations, open MCP Servers → + Add MCP server, paste https://api.ref.tools/mcp (add any headers under Advanced settings), then click Test & save.

### OpenClaw

Run in your terminal:

```shell
openclaw mcp add ref-mcp --url https://api.ref.tools/mcp --transport streamable-http
```

If it needs a key or sign-in: For https://api.ref.tools/mcp, add --header NAME=value for each header it needs, or --auth oauth and then run openclaw mcp login ref-mcp.

### OpenCode

Run in your terminal:

```shell
opencode mcp add ref-mcp --url https://api.ref.tools/mcp
```

If it needs a key: For https://api.ref.tools/mcp, add --header 'NAME=value' for each header it needs. Add --global to use it in every project.

### Hermes Agent

Run in your terminal:

```shell
hermes mcp add ref-mcp --url https://api.ref.tools/mcp
```

Add to ~/.hermes/config.yaml:

```json
{
  "mcp_servers": {
    "ref-mcp": {
      "url": "https://api.ref.tools/mcp"
    }
  }
}
```

If it signs in with OAuth: If https://api.ref.tools/mcp asks you to sign in, add --auth oauth to the command, or auth: oauth to its entry.

---
From Pluginboard (https://pluginboard.ai).