Ref MCP

What is Ref MCP?

Ref MCP is a Model Context Protocol server that gives your AI coding tool or agent access to documentation for APIs, services, and libraries. It is designed for developers using LLM-based coding agents who need fast, token‑efficient access to up‑to‑date documentation.

How to use Ref MCP?

Install via npm (npx ref-tools-mcp) or connect via the streamable HTTP server at api.ref.tools/mcp. Use the tools ref_search_documentation (with a query string) and ref_read_url (with a URL) to search and fetch documentation.

Key features of Ref MCP

• Deduplicates search results within a session.
• Returns only the most relevant 5k tokens per page.
• Reduces context rot by minimizing irrelevant tokens.
• Supports both streamable HTTP and stdio transports.
• Works as a documentation source for OpenAI deep research.
• Tracks search trajectory across MCP sessions.

Use cases of Ref MCP

• Querying API documentation for a specific endpoint.
• Fetching library usage examples with minimal token cost.
• Keeping an AI coding agent updated on multi‑step workflows.
• Reducing costs by pulling only relevant parts of large docs.
• Supporting research workflows that need repeated refined searches.

FAQ from Ref MCP

What exactly does Ref MCP do?

It provides two tools: ref_search_documentation searches for relevant documentation based on a natural language query, and ref_read_url fetches the content of a URL, converting it to markdown and returning the most relevant portion (up to 5k tokens).

How do I get an API key?

Sign up at ref.tools to obtain an API key. The key is required for both the HTTP and stdio setup methods.

What transports does Ref MCP support?

Two transport options: streamable HTTP (recommended) and local stdio. The HTTP server URL is https://api.ref.tools/mcp?apiKey=YOUR_API_KEY; the stdio command is npx ref-tools-mcp@latest with the environment variable REF_API_KEY.

How does Ref MCP minimize token usage?

It deduplicates repeated search results in a session and fetches only the most relevant 5k token portion of a page based on the agent’s search history, avoiding the common problem of pulling 20k+ irrelevant tokens from large documentation pages.

Why is minimizing token context important for AI agents?

More context can make models less accurate (context rot), and extra tokens cost money—for example, 6k irrelevant tokens in a step using Claude Opus can waste ~$0.09 per step, adding up across multiple steps.