Ref MCP

Ref MCP

Ref MCP is a Model Context Protocol (MCP) server designed to provide AI agents and coding tools with efficient, up-to-date access to technical documentation for APIs, libraries, and services. It enables precise, token-efficient retrieval of documentation context to enhance code understanding and automation.

Author: ref-tools


View Protocol

What is Ref MCP?

Ref MCP is a specialized MCP server that connects coding agents and developer tools to a curated universe of technical documentation. It empowers agents to search, retrieve, and analyze the most relevant parts of documentation on demand, minimizing token usage and improving LLM performance when working with APIs and libraries.

How to Configure Ref MCP

There are two main methods to set up Ref MCP as an MCP server:

1. Streamable HTTP (Recommended):

  • Install Ref MCP through supported clients (such as Cursor) by using provided install links or by directly specifying server configuration: 
    "Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}
  • You need to sign up at ref.tools to get an API key.

2. Local stdio Server (Legacy):

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <your_api_key>
  }
}
  • Requires Node.js and npm.

Optionally, for local development and debugging, you can clone the Ref MCP repo, install dependencies with npm install, and run with npm run dev.

How to Use Ref MCP

  1. Connect your MCP-capable agent or tool to the Ref MCP server using the configuration described above.
  2. Use available tools, such as ref_search_documentation to search API docs, or ref_read_url to fetch and distill relevant documentation content.
  3. Agents can perform iterative search and reading, intelligently reducing context to only what is necessary for code generation or comprehension.
  4. For OpenAI integrations, Ref MCP automatically maps its tools to OpenAI-compatible function names.

For development and inspection, use the MCP Inspector to visually test and monitor interactions.

Key Features

  • Token-efficient documentation retrieval: Returns only the most context-relevant sections, avoiding excessive token costs and performance degradation.
  • Iterative, agent-friendly search: Adapts search results across a session, never repeating results for similar prompts.
  • On-demand context enrichment: Enables LLMs to pull documentation exactly when and where needed.
  • Supports both public and private sources: Search across public docs, web pages, GitHub, and private resources such as internal repos or PDFs.
  • Integrated session management: Tracks search and read trajectory within an agent session for optimal context curation.
  • OpenAI compatibility: Automatically adapts tool naming for seamless usage with OpenAI’s research and coding agents.

Use Cases

  • AI-powered code assistants: Augment coding agents (like Claude Desktop or Cursor) with precise technical documentation access.
  • Automated API integration: Help agents understand, implement, and troubleshoot API endpoints by surfacing the most relevant documentation.
  • Code review and audit bots: Equip agents with the ability to fetch and cite authoritative docs while reviewing code.
  • Developer onboarding tools: Dynamically answer common dev questions by searching and extracting info from company or public docs.
  • Deep technical research: Efficiently query multiple sources and focus on the smallest possible context set for accurate answers.

FAQ

Q1: Why is minimizing tokens in documentation context important?
A1: LLMs tend to perform worse with large, noisy context windows and tokens cost money. By pulling just the relevant parts of documentation, Ref MCP boosts LLM performance and reduces unnecessary API spend.

Q2: What kinds of documentation can Ref MCP search?
A2: Ref MCP searches a broad range of public documentation (APIs, libraries, web docs), and can also index private/internal resources, including GitHub repos and PDFs.

Q3: How does Ref MCP ensure that LLM agents avoid reading the same content repeatedly?
A3: Within an active session, Ref MCP tracks previous searches and returned results, ensuring that each similar search yields new, non-duplicated documents, promoting efficient prompt engineering.

Q4: Can I use Ref MCP with my own agent or tool?
A4: Yes, any agent or application supporting the MCP protocol can connect with Ref MCP using either HTTP or stdio modes.

Q5: What is the difference between ref_search_documentation and ref_read_url?
A5: ref_search_documentation finds relevant documentation links and context by query; ref_read_url fetches and transforms the target page into a markdown summary for easy agent consumption.