Ref Tools Ref Tools MCP

What ref-tools-ref-tools-mcp does

The ref-tools-ref-tools-mcp MCP server connects an AI coding client to Ref’s documentation search and reading service. It is intended for questions about APIs, services, libraries, and other technical resources. Search can cover public web and GitHub documentation, as well as private resources such as repositories and PDFs.

The service is designed to return the context needed for a coding task rather than an entire documentation site. It can help an agent locate an endpoint, compare implementation options, find a code example, or identify the relevant section of a long reference page.

How it works

An agent starts with a natural-language documentation query. Ref returns relevant results and URLs, which the agent can then pass to the URL-reading tool. The reader converts the selected page to Markdown and uses the session’s prior search history to focus on the most relevant material.

Search history also affects repeated searches. Results already returned in the same session are not repeated, allowing an agent to refine its query while continuing to explore additional sources. When a page is large, Ref returns the most relevant portion, with the README describing a target of roughly 5,000 tokens rather than routinely placing 20,000 or more tokens of unrelated page content into context.

This session-aware workflow makes the ref-tools-ref-tools-mcp MCP server most suitable for coding agents that can search, inspect a result, and refine the question as they work.

Setup and configuration

The recommended deployment uses Ref’s streamable HTTP MCP endpoint:

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

The repository also contains a legacy stdio server. It can be launched with npx ref-tools-mcp@latest and requires the REF_API_KEY environment variable:

{
  "Ref": {
    "command": "npx",
    "args": ["ref-tools-mcp@latest"],
    "env": { "REF_API_KEY": "YOUR_API_KEY" }
  }
}

An API key is obtained by signing up through Ref. For local development, the repository documents npm install, npm run build, npm run watch, and npm run inspect; the latter uses MCP Inspector for testing and monitoring.

Tools and capabilities

The server exposes two MCP operations:

• query: searches technical documentation using a required natural-language query.
• url: fetches a specified webpage and converts it to Markdown for reading.

The README also describes equivalent names for OpenAI deep research clients: the search operation maps to search, and URL reading maps to fetch.

Limitations and notes

The repository’s local package is the legacy stdio implementation; streamable HTTP is the recommended setup. The server depends on an API key, and the material does not specify pricing, rate limits, indexing coverage, or guaranteed freshness for individual sources. Search and page reading are separate operations, so an agent generally needs a result URL before it can request focused page content.

The ref-tools-ref-tools-mcp MCP server is focused on documentation retrieval. The provided material does not describe tools for executing API calls, editing repositories, or changing external systems.