SKILL 10 / MCP · DEEP DIVE

Docs-Retrieval MCP: Curing the Training-Cutoff Problem

Context7 taken apart · First-party doc servers · When pasting the page beats retrieving it

2026-09-11 · BigCat

The model confidently writes a parameter name. You go look it up. There is no such parameter. It is not lying — the version it remembers is the one that existed on the day its training stopped.

Related → Skill 09 MCP Server Roundup (that issue mapped the whole field and the context tax; this one drills into the documentation line alone)

// WHY THIS MATTERS

Documentation-retrieval servers are the least controversial category in MCP: they do not touch your files, do not call paid APIs, do not need write access. They pull a chunk of official documentation into context, and nothing else. The illness they treat is equally narrow — model knowledge has a cutoff date, and the libraries you depend on ship every week.

The best-known member is Context7 (roughly 61.9k stars, MIT, per its GitHub repo page, 2026-09). But the point of this issue is a distinction: a general aggregator that indexes every library is a different animal from the first-party doc servers run by Microsoft, AWS, Cloudflare and Anthropic themselves. The aggregator is broad, and its index quality is not yours to control; the first-party ones are narrow, but what they return is the source. Nine installable items follow, and the last section answers the question most worth asking: when you should install none of them.

// 01

What it takes off your plate: "let me go check the docs and get back to you"

Claim: what it replaces is not your search engine, it is the thirty seconds you spend tabbing out mid-conversation, copying a paragraph, and pasting it back. The real win is not the time saved — it is that the model now holds version-specific source text instead of its memory of some older release.

The first thing you can actually run

# 1. The official zero-auth one, useful for proving the plumbing works
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list          # expect a ✔ Connected line

# 2. Context7: one command; it asks whether you want CLI+Skills or MCP mode
npx ctx7 setup --claude  # Node 18+; OAuth sign-in generates an API key
npx ctx7 remove          # the undo

# Wiring MCP mode by hand means this URL, key in the Authorization header
https://mcp.context7.com/mcp

# Your first prompt (the slash syntax names the library, skipping the lookup):
Implement email/password sign-up with Supabase. use library /supabase/supabase
# Want a specific release? Just say it: "How do I set up Next.js 14 middleware?"

Two details are worth noticing. First, ctx7 setup now offers two modes: CLI + Skills, which installs a skill that teaches the agent to shell out to ctx7 library and ctx7 docs and needs no MCP at all, or the traditional MCP server. That is a live example of something this series keeps returning to — the same capability can ship as a server or as a skill plus a CLI. Second, the README calls the API key "recommended", not required; the free key buys higher rate limits.

Failure mode: installing it, adding no trigger rule, then complaining that the agent never uses it. Context7's own fix is a line in CLAUDE.md: "Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask." The skill route from ctx7 setup wires this up for you; hand-wired MCP does not.
Primary sources · upstash/context7 README (every command and tool name above is copied from it) · Claude Code · Connect to MCP servers (where the claude-code-docs command comes from)
// 02

Mechanism: it works because it splits "look it up" into two steps

Claim: nearly every server in this category has the same shape — resolve a library name from natural language into a stable ID, then fetch fragments using that ID plus your question. What makes it work is not the crawling; it is that step two retrieves rather than dumping the whole page.
CONTEXT7'S TWO TOOLS (copied from the official README) ────────────────────────────────────────────────────────────── resolve-library-id query + libraryName -> /vercel/next.js query-docs libraryId + query -> relevant doc chunks ────────────────────────────────────────────────────────────── THE SAME SHAPE ELSEWHERE Microsoft Learn microsoft_docs_search -> microsoft_docs_fetch AWS Docs search_documentation -> read_documentation GitMCP search_*_documentation -> fetch_*_documentation Ref ref_search_documentation -> ref_read_url ────────────────────────────────────────────────────────────── Locate first, fetch second. The fetch always carries your question.

Why the question has to travel with the fetch

Because a full doc page routinely runs twenty or thirty thousand tokens and the model needs one section of it. Ref's author states the case bluntly — "Models get dumber as you put in more tokens" — and the server returns roughly the most relevant 5k tokens of a page instead of the usual 20k+ full fetch (per its GitHub README, 2026-09). Microsoft Learn hands you the dial directly: append ?maxTokenBudget=2000 to the endpoint and search responses are truncated to that budget.

The property people miss: the index is not yours

Context7's README carries two disclaimers that matter: library documentation is community-contributed, with no guarantee of accuracy, completeness or security, and only the MCP server itself is open source — the API backend, parsing engine and crawling engine are private. That is not a knock on it; it is the shared structure of every aggregator. The quality of what you retrieve depends on what someone else's crawler happened to capture. First-party servers (learn.microsoft.com, AWS, Cloudflare, code.claude.com) do not have this problem, because the docs and the service ship from the same building.

Failure mode: reading "Context7 has nothing on that" as "that API does not exist". Three different things produce that answer — the library was never indexed, it was indexed but that page was not crawled, or it was crawled but retrieval missed. None of the three means non-existent.
Going deeper · ref-tools/ref-tools-mcp (source of the token-efficiency argument) · MicrosoftDocs/mcp (the maxTokenBudget documentation)
// 03

Real usage and limits: nine items, installed in three tiers

Claim: do not pick by star count. Pick by who owns the thing you are looking up. If a first-party server covers it, never let an aggregator relay it for you.

Tier one · First-party (use it whenever it covers your question)

Tier two · General aggregators (broad coverage, someone else's index)

Tier three · Repository-shaped (when there is no docs site at all)

Failure mode: installing all three tiers, so four tools compete to answer the same question, the model picks one each time, and you never know whether today's answer came from first-party documentation or from some crawler's cache. One per tier is the basic discipline here.
Going deeper · GitMCP (config snippets for every client) · Microsoft Learn CLI: npx @microsoft/learn-cli search (same tools, no MCP client needed)
// 04

Cost and alternatives: when pasting the page is simply better

Claim: the overhead of documentation retrieval is not in the tool definitions, it is in the return values — every hit pours a few thousand tokens of unfamiliar text into context. If you keep retrieving the same section of the same page, you are paying repeatedly for something that should have been cached once.

Three ways to install nothing at all

The honest costs

The honest cost: this is the category most likely to feel great and change nothing. There is really only one test — in the past week, did it stop you making one version mistake? If you cannot answer, uninstall it.
Going deeper · Claude Code · MCP reference (scopes, auth, disabling) · code.claude.com/docs/llms.txt (a real llms.txt in the wild)

// THE ONE-PAGE BUYING CARD

Install these three first: (1) claude-code-docs — claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp, zero auth, and it proves your MCP plumbing works; (2) context7 — npx ctx7 setup --claude, plus that trigger line in CLAUDE.md; (3) whichever first-party server matches your main cloud — https://learn.microsoft.com/api/mcp for Azure/.NET, uvx awslabs.aws-documentation-mcp-server@latest for AWS, https://mcp.cloudflare.com/mcp for Cloudflare.

Add on demand: gitmcp.io/{owner}/{repo} for the days you are chewing through an undocumented repo · mcp.deepwiki.com/mcp to get a map of an unfamiliar codebase · Ref only when what you need to search is private documentation.

Explicitly do not install: a second server in a tier you already cover (no aggregator on top of a first-party server) · anything added "just in case I ever need to look that up" · the stale @upstash/context7-mcp command copied from an old blog post.

The one-line test: use whoever owns the thing you are looking up; reach for an aggregator only when ownership is unclear; and when one page gets consulted five times, paste it.

// GLOSSARY

training cutoff
The last date reflected in a model's parametric knowledge. APIs shipped after it, parameters renamed after it, patterns deprecated after it — the model does not know, and will confidently write the old shape anyway.
library ID
The stable address an aggregator assigns each library, such as /vercel/next.js. Naming it directly in a prompt skips the fuzzy-matching step.
first-party docs server
A retrieval service run by the authors of the documentation. The difference from an aggregator is not features, it is the absence of a third-party crawler in the middle.
token budget
A dial capping how much a single call returns. Microsoft Learn's ?maxTokenBudget=2000 is a rare case of exposing it to the user directly.
llms.txt
A Markdown index file at a site or docs root that tells a model which pages exist, as a linked list. Requires no server of any kind.
injection surface
Any channel that carries untrusted external text into context. Documentation retrieval is one by definition.

// FURTHER READING