Name: Ref
Author: ref-tools

LABSCO SUMMARY

One search covers the public docs and your own.

What it takes off you is knowing where the answer lives: the same query runs over public documentation, GitHub and the private repositories and PDFs you have connected, and whichever result matched is read back as Markdown in the next call.

What it is

A two-call documentation lookup: a search that returns URLs, and a reader that turns a URL into Markdown. Private sources — repositories and PDFs — are searched alongside public ones.

What you get

A documentation search spanning the web, GitHub, and private repositories and PDFs
Any URL from those results read back as Markdown

Requirements

For local stdio, have npx on your PATH and set REF_API_KEY to your Ref API key. The hosted endpoint needs no local npx; authenticate with your Ref API key or OAuth sign-in.

Setup effort

One command plus a key — npx -y ref-tools-mcp, then supply credentials

See installation options

USE CASES

01

Answering a question the public docs do not cover

Internal repositories and PDFs are searched in the same pass as the public web, so a convention that only exists in your own documentation still comes back.

ref_search_documentationref_read_url

02

Reading the source rather than the snippet

Search results give you the page; the second call gives you what is on it, as Markdown the model can quote from.

ref_read_url

03

Checking a library's real API before writing against it

Search the library's documentation by name and read the page, instead of writing from what the model remembers of an earlier version.

ref_search_documentationref_read_url

2 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`ref_read_url`

Read the content of a url as markdown. The EXACT url from a 'ref_search_documentation' result should be passed to this tool.

BEFORE YOU INSTALL

What to know first

Tools you get

2 tools when we connected. Under an OpenAI client the two tools are renamed search and fetch. This repository is the legacy stdio server; the project recommends its hosted streamable-HTTP endpoint instead.

Requires

A Ref account is required: use an API key for either setup, or OAuth sign-in for the hosted endpoint.
The free tier includes 200 one-time credits that never expire and do not renew. Each search or read uses 1 credit; once they run out, continued use requires a paid plan.

Where it runs

Of the 2 documented setups, 1 runs the server on your machine and 1 connects to a hosted endpoint.

CONTEXT COST

Light Standing cost

Rated by the size of the 2 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

npx

TERMINAL

npx -y ref-tools-mcp

Hosted endpoint

ENDPOINT URL

https://api.ref.tools/mcp?apiKey=<YOUR_API_KEY>

Use your Ref API key from ref.tools/keys as <YOUR_API_KEY> in the endpoint URL’s apiKey parameter.

MCP Clients

Any MCP client — HTTP

ANY MCP CLIENT — HTTP · JSON

{
  "mcpServers": {
    "Ref": {
      "type": "http",
      "url": "https://api.ref.tools/mcp?apiKey=<YOUR_API_KEY>"
    }
  }
}

Any MCP client — stdio

ANY MCP CLIENT — STDIO · JSON

{
  "mcpServers": {
    "Ref": {
      "command": "npx",
      "args": [
        "ref-tools-mcp@latest"
      ],
      "env": {
        "REF_API_KEY": "<YOUR_REF_API_KEY>"
      }
    }
  }
}

Ref