AgentIndex icon
AgentIndex
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompareGuides
Submit Tool
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompare
Home/
Code Assistant/
ref-tools-mcp
ref-tools-mcp logo

ref-tools-mcp

Active·★ 1.2k·MIT·Updated 2026-11-06
★ Essential

Ref MCP is a Model Context Protocol server that gives a coding agent access to documentation for APIs, services and libraries. The README's pitch is token efficiency: models get worse as context grows and tokens cost money, so Ref tries to find exactly the context the agent needs. It exposes two tools. `ref_search_documentation` searches public documentation on the web and GitHub, and can also search private resources such as repos and PDFs; its query should be a full sentence or question. `ref_read_url` fetches a page and converts it to markdown.

The README says it uses MCP sessions to track the search trajectory. Repeated similar searches in a session do not return the same results again, and when reading a page it uses the session's search history to drop less relevant sections and return the most relevant ~5k tokens instead of pulling in 20k+ tokens of a large docs page. Its examples show an agent making a short search followed by one read, with token counts for each step.

© 2026 AgentIndex.app|Built by a 10-year iOS Developer.
Best by use caseAboutContactAdvertisePrivacy PolicyTerms of UseQYSGitHubBuy me a coffee ☕

Browse by Category

MCP ServersCode AssistantWorkflow AutomationRAG / Knowledge BaseMulti-AgentBrowser AutomationLLM InfraDev ToolingObservability

Not affiliated with Anthropic, OpenAI or Microsoft.

Guides

This repository holds the legacy stdio server. The README recommends the streamable-HTTP server at `https://api.ref.tools/mcp` with an API key from ref.tools, and the stdio setup (`npx ref-tools-mcp@latest`) also needs a `REF_API_KEY`. So the search itself depends on the vendor's hosted service. The code is MIT licensed and was last pushed on 2026-10-01. This review is based on the README and repository data; we have not run it ourselves.

This write-up is based on the project's README and public repository data. We have not hand-tested the tool. Data as of 2026-11-10.

License
MIT
Latest release
No GitHub releases
Last commit
2026-11-06
Contributors
7
Forks
72
Open issues and PRs
13
First published
2025-04-22

Source: GitHub, npm and PyPI public APIs.

#AI Agent#Documentation Retrieval#Token Efficiency#Context Management#ModelContextProtocol#Code Assistant#API Tooling
$ Install
$ npx ref-tools-mcp@latest
↗ Visit site★ GitHub
01

Features

01Agentic search tailored for AI models, minimizing context usage.
02Intelligent filtering of search results, avoiding repetition within a session.
03Extracts only the most relevant sections (up to 5k tokens) from documentation pages.
02

Why choose it

+Built to keep documentation context small: no repeated results in a session, and page reads return only the most relevant ~5k tokens
+Two simple tools, search and read-URL, usable from Claude Code, Cursor and other MCP clients
+Can search private resources such as repos and PDFs as well as public docs
+MIT-licensed client; install with `npx ref-tools-mcp@latest`
03

Trade-offs

!Needs an API key and a call to the hosted ref.tools service, so your queries go to the vendor and it is not self-contained
!This repository is the legacy stdio server; the recommended HTTP server is not in it
!The token-saving numbers in the README are example traces from the project, not independent benchmarks
!Last push was 2026-10-01
05

Maintenance check

ActiveChecked: 2026-11-10
Last commit
2026-11-06
Commits, last 90 days
5
Releases, last 90 days
0
Latest release
—
Open issues
13
Recent issues with at least one comment
8/10
Commits per week, last 12 weeks
Commits per week, last 12 weeks: 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 1, 0

Oldest week on the left; the latest four weeks are orange. Source: GitHub commit activity.

Status rule: archived on GitHub = Archived; last commit within 90 days = Active; 91 to 365 days = Slowing; older = Stale. All figures come from the GitHub API on the date shown.

04

Who it fits

Pick it if
  • Context size is your main concern: page reads return about the most relevant 5k tokens, and repeat searches do not return the same results in a session.
  • You want two simple tools, search and read-URL, in Claude Code, Cursor or another MCP client.
  • You want to search private resources such as repos and PDFs alongside public docs.
Look elsewhere if
  • You cannot send queries to a vendor: it needs an API key and the hosted ref.tools service.
  • You want the recommended HTTP server: this repository is the legacy stdio server.
  • You need independent proof of the token savings: the README's numbers are the project's own example traces.
06

How it differs

Context7 logovs Context7★ 65.2k

Context7 resolves a library and returns its docs and examples. Ref focuses on trimming what comes back to the most relevant part.

Full comparison →
07

Compatibility

Node.js
Runtime
Verified via docs
ModelContextProtocol
Protocol
Verified via docs
AI Coding Tools
Integration
Verified via docs
08

Quick start

1
$ npx ref-tools-mcp@latest
09

Use cases

↳Providing specific API documentation to AI coding agents for development tasks.
↳Enabling LLMs to refine search queries and understand complex coding best practices iteratively.
↳Optimizing context for AI agents to reduce inference costs and improve model accuracy.
10

Alternatives

⚡Top VS:
VSContext7★65.2k→VSGemini CLI★109.0k→VSOpen Interpreter★68.9k→

Featured in these lists

  • Best MCP Servers for Up-to-Date Docs and Code Context

Comments

Log in to leave a comment

No comments yet. Be the first!

On this page
01Features02Why choose it03Trade-offs05Maintenance check04Who it fits06How it differs

Most discussed open issues

  • #32 Support for adding external document URLs to the index7 comments · 2025-10-28
  • #10 Is ref-tools-mcp self hostable?3 comments · 2025-07-25
  • #39 Company invoicing1 comments · 2026-02-08
  • #60 [read-only MCP health check] handshake incomplete: NO_RESPONSE0 comments · 2026-10-11
  • #52 ai.smithery/ref-tools-ref-tools-mcp is listed on Fatstack — claim it, or ask us to remove it0 comments · 2026-09-14

Issue titles are quoted from GitHub. Open the link to check whether a problem still applies to the version you use.

VS
pal-mcp-server
★11.8k
→
Context7 logo
Context7★ 65.2k
MCP Server that provides up-to-date code documentation for LLMs and AI code editors.
VSCompare→
Gemini CLI logo
Gemini CLI★ 109.0k
An open-source AI agent that brings the power of Gemini directly into your terminal. Supports native MCP.
VSCompare→
Open Interpreter logo
Open Interpreter★ 68.9k
A coding agent for the terminal, optimized for low-cost and open models. Forked from OpenAI's Codex, it can emulate other agent harnesses and runs commands in a native sandbox.
VSCompare→
pal-mcp-server logo
pal-mcp-server★ 11.8k
The power of Claude Code / GeminiCLI / CodexCLI + [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.
VSCompare→
Trail-Code logo
Trail-Code★ 11.4k
Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
VSCompare→
zcf logo
zcf★ 6.1k
Zero-Config Code Flow for Claude code & Codex
VSCompare→
claude_code_vs logo
claude_code_vs★ 108
Bring Claude Code to Visual Studio 2026: a native diff with accept/reject, a live debugger Claude can drive, Roslyn code navigation, and Test Explorer integration. The IDE half of Claude Code's integration protocol. Community-built, unofficial.
VSCompare→
code-buddy logo
code-buddy★ 51
Open-source AI coding agent that runs free on your own machine (local Ollama, $0) — or bring any of 15 providers (Claude, GPT, Gemini, Grok) with automatic failover. Terminal, desktop & 24/7 server.
VSCompare→
See all alternatives →
07
Compatibility
08Quick start
09Use cases
10Alternatives
ref-tools /
ref-tools-mcp
↗

MIT MCP server for documentation search that returns only the relevant tokens, via a hosted Ref service with an API key

1.2k72MIT
Last commit2w ago
StatusActive
CategoryCode Assistant
Contributors7
Links
Documentation↗Discussion↗Issues↗Releases↗
Cloud Infrastructure
Ad

Deploy on DigitalOcean

Host your MCP servers, Docker containers, and AI agents with $200 free credit over 60 days.

Claim $200 Free Credit