Docs-Backed MCP Server vs Custom Knowledge API

Anthropic released the Model Context Protocol as an open standard in November 2024. By April 2025, SDK downloads had climbed from roughly 100,000 to over 8 million. By December 2025, Anthropic's own ecosystem reporting put monthly SDK downloads above 97 million. As of a May 2026 snapshot, the official MCP Registry carried nearly 9,652 server records; over 15,900 GitHub repositories carry the mcp-server topic. Stacklok's 2026 software report found that 41% of surveyed organizations had MCP servers in limited or broad production use.

Those are not curves you see for speculative infrastructure. But speed of adoption has a way of foreclosing questions that are still worth asking.

The governance picture accelerated the same way. Anthropic donated MCP to the Linux Foundation's Agentic AI Foundation in December 2025, with Anthropic, OpenAI, Block, and others now co-governing the standard. Then OpenAI deprecated its proprietary Assistants API in favor of MCP, with a mid-2026 sunset. When the organization that built one of the dominant competing agent frameworks abandons it to join a shared protocol, the standards competition is effectively over. Gartner projects that 75% of API-gateway vendors and 50% of iPaaS vendors will offer MCP features by 2026, which suggests the infrastructure layer is reorganizing around the protocol rather than waiting to see how it lands.

What MCP actually solves is what practitioners call the M×N integration problem. Before a shared protocol, every agent needed custom connector code for every data source: four data sources and three agents meant twelve bespoke integrations to build, test, and maintain. MCP reduces that to one server per data source, one client per agent. The arithmetic becomes more favorable as either dimension grows.

The protocol achieves this through three primitive types: Resources, which are readable data; Tools, which are callable functions; and Prompts, which are reusable templates. Transport runs on JSON-RPC 2.0, either over stdio for local synchronous use cases or SSE for remote streaming. Sessions are stateful across tool calls, so an agent does not re-authenticate or re-establish context between workflow steps. This is architecturally distinct from REST, where every request is stateless and the caller must supply full context each time.

The behavioral shift that matters most in practice is tool discovery. When an MCP client calls tools/list, the server replies with natural-language descriptions of its capabilities and structured input schemas. The agent reads those descriptions and decides at runtime which tool to invoke. A REST API requires a developer to read documentation, understand endpoints, and hardcode integration logic before deployment. MCP moves tool selection from a design-time decision made by a human to a runtime decision made by the agent. That is not an incremental improvement; it changes the category of work that is possible without a developer in the loop.

MCP does not replace APIs. The underlying REST calls still execute. The protocol standardizes the AI-facing interface that sits above them.

What this produces, at the team level, is a shift in default assumptions. Scoping agentic work in 2026 increasingly starts from MCP as the assumed architecture. Choosing a custom knowledge API instead is a deliberate departure from that default, and deliberate departures now carry a burden of justification they did not carry eighteen months ago.

What a Docs-Backed MCP Server Actually Is and How the Retrieval Layer Works

A docs-backed MCP server is an MCP server whose primary function is exposing documentation, knowledge-base content, or structured reference material to LLM agents via standardized tools. The architecture has three distinct layers: the MCP protocol layer, handling tool registration, discovery, and session state; a retrieval pipeline, typically retrieval-augmented generation over a vector index; and a document ingestion and embedding pipeline that converts markdown, HTML, or structured formats into vector representations.

Retrieval modes vary by implementation: dense semantic search, lexical keyword search, or a hybrid of both. Results often include neighboring context and diversification logic to reduce redundancy in what the agent receives.

The design principle that differentiates this from a conventional API is where the interface contract lives. In a docs-backed MCP server, each tool is a function whose docstring becomes the agent's semantic contract. The agent reads that docstring to understand the tool's purpose, parameters, and appropriate usage patterns. The documentation is not auxiliary metadata; it is the interface itself. A poorly written docstring produces a miscalibrated tool call regardless of how good the underlying retrieval logic is.

What this failure looks like in practice is not obvious until you have chased it. The surface behavior is unremarkable: the agent is making tool calls, calls are returning results, the system appears functional. The actual problem surfaces later, when you trace why the agent keeps selecting the wrong retrieval path and find a docstring that was technically accurate but semantically ambiguous, ambiguous enough that the agent's matching logic landed on the wrong tool with full confidence. The retrieval pipeline was fine. The descriptions were the problem. Nobody had thought to audit them because nothing had obviously broken.

The production examples clarify the range. AWS released its Knowledge MCP Server into general availability in October 2025; it surfaces documentation, blog posts, Well-Architected guidance, and regional API and CloudFormation availability data, with no AWS account required. Microsoft's Learn MCP Server supports document search, full article retrieval, and code sample search, with a knowledge service that runs incremental refreshes after content updates and a full daily rebuild; it explicitly requires an agent framework as its client. Google's Developer Knowledge API and MCP Server entered public preview in February 2026, supporting cross-domain search across more than eleven Google developer documentation domains.

One documented RAG implementation operated across more than fifty documentation sites, with custom embeddings stored in ChromaDB and modular separation of ingestion, indexing, retrieval, and conversation management. The modularity matters because each layer can be updated or replaced without rebuilding the whole system.

There is an architectural implication here that teams frequently underweight: a docs-backed server's usefulness degrades directly with documentation staleness, and the degradation is quiet. The server keeps returning results; the results are simply losing their grounding in current content. Microsoft's incremental-plus-daily-full-refresh approach is the production answer to that problem. The teams that skip it tend to discover the gap through user complaints rather than monitoring.

What a Custom Knowledge API Is and Where It Genuinely Fits

A custom knowledge API is a purpose-built REST or GraphQL endpoint that exposes a documentation or knowledge corpus to callers, including agents, via standard HTTP request-response semantics. The caller must understand the API contract in advance: endpoints, authentication, query format, response schema.

That requirement is a feature in some contexts and friction in others. For a deterministic system, or a human developer who will read documentation and write integration code, a stable versioned contract is exactly what you want. For an autonomous agent that needs to discover and invoke capabilities at runtime, the same requirement becomes a constraint the agent cannot satisfy without developer assistance at build time.

The strengths of the custom knowledge API are concrete. Universal compatibility is one: a REST endpoint works in any environment, not just those with MCP-aware clients. Versioning semantics are well understood. Teams with existing API infrastructure can expose documentation to agents as one caller type alongside human developers, dashboards, and non-agent systems, without restructuring anything. For proprietary or regulated documentation corpora, the closed data loop, where content never leaves infrastructure the team controls, is a meaningful and auditable security control.

The case for custom APIs is also clearest where no vendor MCP server covers the required corpus. Internal documentation, proprietary knowledge bases, organization-specific reference material: none of this appears in off-the-shelf MCP servers. A custom API is frequently the only viable path to surfacing that content to an agent at all.

The counterargument is build cost, and it is routinely underestimated. Retrieval that performs well under load, with appropriate relevancy ranking, takes more time and resources than initial estimates typically allow. Open-source tooling covers much of the plumbing; tuning and ongoing maintenance are real costs that rarely make it onto the project plan. Roughly 42% of companies abandoned most of their AI initiatives in 2025, according to data cited across that period, with over-engineered custom solutions representing a meaningful share of the wreckage. Building a bespoke retrieval system before there is evidence the investment is justified carries organizational risk, not merely technical risk.

Even in environments where MCP is the primary integration layer, a well-designed custom API retains its value as a defensible fallback. The same documentation results available through an MCP server can, in principle, be accessed by calling REST directly when an MCP client is unavailable. That optionality matters precisely because agent client stacks are still in flux.

The Integration and Maintenance Math That Separates the Two Approaches at Scale

Return to the M×N problem with concrete numbers. Four data tools, three agents, no shared protocol: twelve separate integrations, each with its own authentication logic, error handling, and schema mapping. With MCP, each of the four tools exposes one server; each of the three agents connects through a standard client; the total implementation count drops to seven. That ratio becomes significantly more favorable as either dimension grows.

Feature propagation is where the maintenance gap is sharpest. When a new capability is added to an MCP server, every connected agent picks it up immediately: no code update, no redeployment, no per-agent testing cycle. The server's tools/list response updates, and the next agent invocation sees the new capability.

Adding the same capability to a custom knowledge API triggers a different sequence. Each agent integration that wants access needs a code update, a redeployment, and a testing cycle. With three or four agent consumers, that is manageable. With a dozen, it accumulates. Every schema change, every new endpoint, every deprecation adds to a deficit that rarely surfaces until someone asks why a particular agent's behavior diverged from expectations three weeks ago and nobody can reconstruct the answer.

Static documentation compounds this. A custom knowledge API whose corpus is not connected to an auto-update mechanism forces documentation drift into every downstream agent response. The API continues to serve results; the results become progressively wrong; and because the agent does not flag uncertainty, users often do not notice until the error has propagated far enough to become a complaint rather than a signal.

Many teams land on a hybrid architecture as a result: stable, high-traffic, deterministic functionality stays on traditional APIs, while dynamic, agent-driven integrations move to MCP. This is not a hedge or a failure to commit. It reflects what each approach is structurally suited to do, and the teams that reach it often do so after learning the hard way why the partition matters.

Context Window Constraints That Docs-Backed MCP Servers Hit in Production

The context window problem in MCP is underappreciated until it becomes a production incident, at which point it is genuinely difficult to diagnose if you have not seen it before.

Each tool definition registered with an MCP client occupies context, with estimates ranging from roughly 550 to 1,400 tokens per tool depending on schema complexity. Load enough tools and the agent begins exhibiting confusion: wrong tool selection, redundant schema definitions consuming tokens that should fund reasoning, degraded response quality with no obvious proximate cause. Research into large-scale MCP deployments cites 916 tools as an illustrative ceiling where tool confusion becomes a material accuracy problem. Most major MCP clients, including VS Code, Cursor, Windsurf, and Claude, impose active limits on simultaneous tool registrations.

For a docs-backed MCP server covering multiple domains or a large multi-section knowledge base, the naive design of one tool per document type hits these limits quickly. The architectural response is consolidation: use the RAG retrieval layer to surface relevant chunks at query time rather than exposing every document category as a separate tool, and invest heavily in docstring quality so the agent can select accurately among a smaller number of well-described tools. The docstring investment is easy to defer and expensive to backfill. The connection between degraded agent behavior and underspecified docstrings is unintuitive to someone who has not traced it, which means it often gets attributed to the model rather than the interface design.

A custom knowledge API does not carry this constraint at all. The agent calls an endpoint and receives results; no tool schema occupies context at registration time. The tradeoff is that the agent cannot discover what the API can do at runtime; that knowledge is baked into integration code at build time, by a developer, before the agent runs.

For teams with very large, highly differentiated documentation corpora, keeping the retrieval layer behind a conventional API endpoint and calling it from a small number of well-designed MCP tools is often the more tractable architecture: MCP on top, REST underneath, with the MCP tool acting as a thin routing layer rather than a direct document-type-to-tool mapping. The abstraction can be inverted without abandoning the protocol. That flexibility is worth keeping in view.

Security Posture Differences Teams Should Account for Before Deploying Either Approach

Security is where the gap between the MCP protocol's design intent and the ecosystem's implementation reality is most consequential, and where the difference between "the protocol is secure" and "this deployment is secure" does the most damage.

An analysis of more than 5,200 open-source MCP server implementations found that 53% rely on hard-coded static secrets, including API keys and personal access tokens. Only 8.5% use OAuth, which is what the MCP specification actually recommends. A scan of popular MCP servers conducted in March 2025 found 43% with command-injection flaws, 22% allowing path traversal or arbitrary file reads, and 30% exploitable via server-side request forgery, with no authentication required.

These are ecosystem-level findings about how MCP servers are built in practice. They are not protocol flaws. The specification is coherent; implementations frequently skip the hard parts in favor of static secrets that are easier to configure and substantially easier to compromise. The problem is auditable and fixable at the implementation level, but only for teams that treat the audit as a required step rather than an assumption. A meaningful number do not, and that gap is where the actual exposure lives.

Custom knowledge APIs inherit security patterns that organizational tooling has decades of experience with: token-based authentication, rate limiting, TLS termination, API gateway policies. Security teams have playbooks for REST APIs. Most lack established playbooks for MCP server audits, and the absence of a playbook correlates reliably with the absence of scrutiny.

MCP's trust model is structurally different in a way worth naming. The protocol assumes the caller is an intelligent but untrusted system that cannot hold secrets or execute code directly; the server exposes capabilities rather than URLs. This is a coherent and defensible security philosophy for an agent-facing interface. Its strength as a design, however, is contingent on authentication actually being implemented, and the ecosystem data suggests a substantial portion of current deployments have not cleared that bar.

For teams handling sensitive or proprietary documentation, the custom API's closed data loop is a concrete control, not an abstract preference. MCP servers routing through third-party agent clients introduce exposure surface that is worth mapping explicitly before any production deployment.

The narrow but non-negotiable practical implication: security maturity in the MCP ecosystem is improving, but teams deploying MCP servers now should audit any off-the-shelf implementation before it reaches production. The protocol's design intent is not a warranty on any particular server's implementation.

How to Map the Tradeoffs to Your Team's Actual Situation

There is no framework here that resolves this cleanly, and I am skeptical of anyone who offers one. The decision turns on constraints that vary significantly across teams: maintenance capacity, agent client stack, documentation update frequency, corpus sensitivity, existing infrastructure. Generalizations about which approach is "better" tend to reflect the generalizer's stack more than anything universally true.

A docs-backed MCP server makes sense when the primary consumers are MCP-aware agent clients, Claude, Cursor, GitHub Copilot, VS Code with MCP extensions, where protocol alignment reduces integration overhead in ways that compound over time. It makes sense when documentation changes frequently and agents need to work from current content; a server with an auto-refreshing retrieval index keeps agents accurate without requiring manual updates across every consumer. It makes sense when the team wants to add or modify retrieval capabilities without touching downstream agent code. It fits when the corpus is large enough to benefit from semantic retrieval but bounded enough not to saturate tool context limits.

The case for a custom knowledge API is equally concrete in different conditions. If agents are one of several caller types alongside human developers, dashboards, or non-MCP systems, REST's universal compatibility is valuable; adding an MCP layer only some callers can use solves a problem that does not exist. If the documentation corpus is proprietary or regulated and a closed data loop is a hard requirement, the custom API path provides cleaner control with security tooling that is already well understood. If existing API infrastructure is in place and well-maintained, introducing an MCP layer adds overhead without proportional benefit. If the corpus is very large with many distinct document categories, context window constraints on MCP clients make a retrieval-behind-API approach more tractable than trying to consolidate an unwieldy number of tools.

The hybrid architecture, stable knowledge endpoints as APIs, agent-facing documentation surfaced via MCP, is often the correct answer. Not because it avoids a hard choice, but because it reflects what each approach is actually good at. The teams that land there tend to do so after discovering, at some cost, why the partition matters.

Which brings up the question most teams ask last and should ask first: how often does the documentation actually change, and who is responsible for keeping the retrieval layer current? A custom knowledge API with a manual refresh cycle that slips will silently degrade every agent that depends on it. The agents continue returning answers; the answers are simply wrong in ways that do not surface until they become user complaints. The protocol choice is secondary to the update architecture, and the evaluation should begin there.