Keeping MCP Server Responses Accurate as Docs Change

Retrieval-augmented generation handles the knowledge cutoff problem differently than MCP, and understanding where each approach buckles is more instructive than the marketing comparison most teams encounter. RAG converts documents to embeddings, stores them in a vector index, and retrieves them at generation time. The system is accurate to the last index job, not to the last document change. A property shipped in a patch release does not exist in the vector store until the next re-index run, and the model has no signal that the gap exists. It answers confidently from what it has.

MCP's live-query model sidesteps this by accessing APIs, databases, and content streams on demand, returning current state rather than indexed state. A 100-query benchmark comparing an MCP server against a RAG implementation on the same Claude model, spanning API lookups, component how-tos, and recent-feature freshness, found that MCP produced the higher-confidence answer in 52% of comparisons versus 38% for RAG, with 10% ties. MCP's largest advantages appeared on exact API interface lookups, where it outscored RAG by 50 to 67 confidence points. RAG's wins clustered on stable styling and theming content, where dense embedding search matched documentation more directly than MCP's keyword-oriented retrieval.

The cost differential is not trivial. MCP ran at roughly 2.5 times higher latency and approximately 36 times higher per-query spend than RAG in the same benchmark. Both figures are reasons to use it deliberately rather than reasons to avoid MCP entirely.

What the data actually suggests is messier than either camp wants to admit: MCP wins on freshness when the underlying documentation is current, and RAG wins on stable content that embeds well. Neither approach rescues poorly maintained documentation; each retrieves it faster. In production, the pattern that has emerged is RAG for searching stable knowledge bases and MCP for live data and actions, the two complementing rather than replacing each other. Teams that reach for one as a universal solution tend to discover the other's use case the hard way.

What the Protocol Itself Does to Keep Context Current Between Server and Client

MCP includes several mechanisms for propagating structural changes between server and client. Resource subscriptions let clients receive notifications when a resource changes, without polling. When a server's available tools change, it emits a JSON-RPC 2.0 notification; the client immediately refreshes its tool registry, meaning an agent mid-conversation can pick up a newly exposed tool without a session restart. Prompt-template changes trigger analogous notifications. The registry requires a unique version string per publication, which creates a traceable change record for each release.

These mechanisms are effective at what they claim to do. But there is a specific limitation worth sitting with, because it tends to get glossed over in protocol documentation: MCP delivers changes; it cannot evaluate the content quality of what is inside those changes. A document can update, trigger a subscription notification, and arrive containing vague descriptions, deprecated examples, or contradictory instructions. The freshness signal fires correctly. The accuracy problem persists.

I have watched teams wire up MCP, confirm that subscription notifications are firing, and declare the freshness problem solved, only to find their agent surfacing stale recommendations three weeks later because the documentation itself had not been updated. The protocol worked perfectly. The content hadn't kept up. These are separate concerns operating at separate layers, and conflating them is one of the more common mistakes in early MCP deployments.

Why Documentation Quality Directly Determines Agent Response Quality

When documentation is the data layer, writing quality and response quality are not loosely correlated; they move together. As Cherryleaf observed in October 2025, improvements in documentation quality immediately translate into better AI responses. Every gap a writer leaves becomes a gap in every agent response that draws from that documentation.

Four attributes shape how well documentation serves agents. Coverage determines whether the agent can surface a feature at all; undocumented features are invisible, and deprecated features left in the docs are recommended with the same confidence as current ones. Precision governs whether the agent can act on what it retrieves; vague instructions like "configure the settings appropriately" give the model nothing to work with, while specific instructions like "set the timeout value to 30 seconds in config.yaml" produce usable responses. Canonical sourcing prevents information drift: the same fact documented in multiple places that have since diverged causes agents to surface inconsistencies, and one authoritative source per fact is the structural solution. Stable, discoverable paths matter because agents and MCP servers need consistent, predictable URLs to retrieve content reliably; opaque or shifting URL structures introduce retrieval failures that look like model failures.

Tool description quality is where this concern becomes engineering-adjacent. An empirical analysis of 103 major MCP servers comprising 856 tools, published on arXiv (2602.14878), found systematic quality problems in tool descriptions with measurable downstream consequences. On well-documented servers, tool-selection accuracy reached 100%. On a poorly described server, it dropped to 84%, with misses clustering on naming collisions that static lint rules could flag. The model did not fail. The documentation did, and the model reflected that faithfully.

Agent usability is as much a writing problem as an engineering problem. That conclusion makes some engineering teams uncomfortable, but the numbers don't offer a more palatable interpretation.

How Bloated and Under-Annotated Tool Schemas Degrade Accuracy at Scale

Token cost is not an abstraction. A single tool definition typically runs 100 to 500 tokens. A five-server, 58-tool setup can burn roughly 55,000 tokens in schema definitions; Jira alone reaches approximately 17,000. When the context window is saturated with schema definitions, agents begin calling the wrong tool. This presents as a model problem. It is a documentation structure problem.

Anthropic's own engineering work on tool definitions, per reporting from KanseiLink in 2026, reportedly reduced token consumption from roughly 134,000 tokens to approximately 5,000 through lazy-loading, an 85% reduction. The optimization was not a model change; it was a schema organization change. That distinction is worth emphasizing because the instinct, when an agent starts misrouting tool calls, is almost always to blame the model.

A parallel failure mode involves missing annotations. Annotations introduced in 2025 and standardized through 2026, including readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, declare how a tool behaves, not just what it does. Per public data, missing annotations account for 30% of Claude Connector Directory rejections. A significant share of MCP servers fail quality review not because the tool does not work but because its description fails to communicate what it does.

Schema quality and annotation completeness are documentation decisions. They have direct, measurable consequences on whether the correct tool gets called in production. Framing them as anything else delays fixing them.

Tooling That Addresses Doc Freshness at the MCP Layer

Several tools have emerged specifically to address the freshness problem at the MCP layer, each working from the same underlying logic: surface current documentation at query time rather than relying on the model's frozen training state.

Context7, developed by Upstash in 2025, pulls version-specific documentation and code examples from source and places them directly into the prompt at query time. It solves the training-cutoff problem for actively maintained libraries where the model's frozen knowledge produces hallucinated or deprecated patterns. By late 2025 it had accumulated over 37,000 GitHub Gemini CLI downloads and more than 500 Reddit mentions, requires no API keys, and uses smart caching to reduce token overhead. A private-documentation extension adds version pinning, source citations, stale-doc checks, and usage receipts.

GitMCP, released as open source in 2025, transforms any GitHub repository or GitHub Pages site into a documentation hub accessible via MCP. It runs in the cloud and requires only adding a GitMCP URL as an MCP server in the IDE, with no downloads, installations, or signups, which makes it accessible for projects the model has never encountered.

LangChain's mcpdoc exposes a user-defined list of llms.txt files and a fetch-docs tool to MCP host applications. The llms.txt convention is analogous to robots.txt but oriented toward language models: pre-processed, optimized summaries of documentation that give agents a clean retrieval target rather than raw HTML.

In production, Microchip Technology's MPLAB-DOCS MCP server uses vector search over technical documentation to ground chatbot and IDE agent responses in current product data, replacing less reliable retrieval patterns with structured MCP access.

Each of these tools works because someone maintained the documentation behind it. The tooling surfaces current docs. It cannot produce them.

Automating the Link Between Code Changes and Documentation Updates

The most tractable version of the doc-freshness problem is the one where documentation lives in the same repository as the code it describes. There, automation can close the gap almost entirely, and the teams that have gotten this right tend to treat the pipeline as load-bearing infrastructure rather than a nice-to-have.

Playwright MCP's CI pattern is a concrete model. The pipeline runs on every push to main and every pull request. A lint job executes a script that regenerates the README from code; a subsequent check fails the build if documentation is out of sync. Documentation staleness becomes a build failure, not a post-release discovery. The discipline this imposes is more valuable than the specific implementation: it makes the cost of a doc gap visible at the moment the gap is created, rather than weeks later when an agent starts surfacing stale responses in production.

GitHub App integration combined with the GitHub MCP Server enables a more autonomous variant: when a workflow fails, an agent investigates, identifies the root cause, and pushes a fix back to the repository as a pull request. The loop closes without human intervention for a well-scoped class of failures.

But MCP has a structural constraint here that deserves explicit acknowledgment. The protocol assumes synchronous request-response interactions; its current transports are not designed for receiving inbound webhooks from third-party services. When documentation changes originate in external systems, a CMS publish, an API registry update, or a third-party changelog event, those changes need to push notifications into an MCP server through architecture that MCP does not natively provide. The 2026 roadmap prioritizes stateless Streamable HTTP across load balancers, improving horizontal scaling, but does not address inbound event ingestion from external services.

Automation works well for docs that live close to code. It requires additional architecture for docs managed in external content systems, and teams building in the latter environment should account for that gap explicitly rather than discovering it in production.

What Ongoing Doc-Sync Operations Actually Look Like in Practice

Documentation behind an MCP server is not a project with a completion state. It is a running operational surface, and the teams that have internalized this tend to staff and schedule accordingly. The ones that haven't tend to notice the problem only after agent accuracy has quietly degraded for a while.

The failure modes that accumulate over time are consistent. Coverage gaps appear when features ship without corresponding documentation; the agent either refuses to answer or fills the gap with hallucination. Deprecated content persists when old endpoints, removed options, or renamed parameters are left in place; the agent recommends them with the same confidence it applies to current functionality. Precision drifts when descriptions that were accurate at launch grow vague as the feature evolves. Canonical drift occurs when the same fact appears in multiple places that have since diverged, and no one has a clear mandate to reconcile them.

Tool schema maintenance is a recurring operational task, not a setup cost. As APIs evolve, tool definitions must be updated, annotations reviewed, and schema size kept within bounds. The version string requirement in MCP's registry creates a natural audit trail, but only if teams treat it as one rather than as a release formality.

The coordination question this raises is uncomfortable for most organizations: documentation quality in AI contexts requires tighter alignment between the people who ship features and the people who document them than most teams currently maintain. The latency between a feature change and a documentation update is no longer an invisible cost. It is directly visible in agent response accuracy, and it compounds as the product evolves.

Treating documentation as living infrastructure, versioned, tested against code, and updated on the same schedule as the product, is what separates MCP deployments where accuracy holds from those where it degrades. The protocol gives agents a path to current knowledge. Whether there is current knowledge at the other end of that path is an organizational and editorial question, and it does not resolve itself.