Exposing Documentation as MCP Tool Endpoints

The Model Context Protocol was published by Anthropic in November 2024 and donated to the Linux Foundation's Agentic AI Foundation in December 2025. It is, by design, vendor-neutral. Its adoption curve has been steep enough to be uncomfortable to ignore: over 97 million SDK downloads, more than 13,000 MCP servers indexed on GitHub, weekly download figures for the Python and JavaScript SDKs exceeding 20 million as of 2026, and formal adoption by OpenAI, Microsoft, Google, and Cloudflare. Gartner predicts that 75% of API gateway vendors will include MCP support by the end of 2026. What you are watching is a protocol crossing from early-adopter curiosity into infrastructure expectation.

The protocol itself is JSON-RPC-based. AI applications open a stateful session with an MCP server and, within that session, discover and invoke capabilities the server exposes. The architectural problem it addresses has a satisfying algebraic framing: without a shared protocol, connecting N tools to M model front-ends requires N × M custom integrations. MCP collapses that to N + M. Anyone who has maintained even a modest number of AI integrations by hand will feel the significance of that difference viscerally.

What this piece is specifically concerned with is documentation. Any MCP-aware agent can, if the documentation is exposed correctly, discover and call it as a live capability rather than passively reading it. That conditional, "if exposed correctly," is where most of the interesting design lives. The path from static reference material to structured, agent-invocable capability is not automatic, and the decisions made along that path determine whether documentation actively powers AI workflows or simply exists alongside them.

Why static documentation fails AI agents at the point of use

Large language models are frozen at their training cutoff. Software documentation is not. Endpoints get deprecated. Authentication flows change. Rate-limit policies are revised. New methods are introduced. The gap between what a model was trained on and what the current API actually does widens continuously after the model ships.

This mismatch produces a particular failure mode that is worth naming precisely because it is so easy to misdiagnose. An agent confidently recommends a deprecated endpoint. The developer follows the recommendation, writes the integration, and then spends hours debugging behavior that doesn't match expectations, eventually realizing the agent's knowledge was simply stale. The bug looks like developer error. It isn't. It is a documentation access problem. But what if the documentation had been exposed as a live, queryable capability rather than a static artifact the model consumed only at training time? That is exactly the question MCP documentation exposure is designed to answer.

By 2026, roughly 82% of developers use AI coding assistants daily or weekly. At that level of adoption, the expectation that an agent can consult accurate, current documentation is no longer a differentiator. It is a baseline. Teams that recognize this are already treating agent-accessible documentation as part of their documentation infrastructure, not as a future enhancement.

The static formats that have served developers adequately for decades, a sidebar rendered in a browser, a PDF, a Markdown file in a repository, solve nothing in this context. An agent cannot consult a sidebar mid-task. It cannot search a PDF at inference time unless something exposes that content as a callable endpoint. MCP tool endpoints are the mechanism designed to close exactly this gap: they transform documentation from something a human reads into something an agent can query at the moment it needs the information.

The three MCP primitives and where documentation fits

MCP defines three primitives: Tools, Resources, and Prompts. Each has a distinct interaction model, and conflating them, which is easy to do when you are moving quickly, produces real problems downstream.

Tools are model-controlled executable functions. The LLM discovers them, decides when to invoke them, and calls them via tools/call. They can modify state, hit external systems, and trigger side effects. The model's autonomy here is the point, but it is also where the risk surface lives.

Resources are application- or user-controlled read-only data identified by URIs. The client application decides when to fetch them and inject them into context. The model does not retrieve a Resource on its own initiative. This distinction matters enormously for documentation.

Prompts are server-defined reusable templates that users select explicitly. They support dynamic runtime arguments and are useful for standardizing recurring workflows, code reviews, bug reports, onboarding sequences. For documentation purposes they have a narrower role: standardizing recurring query patterns, something like "explain this API parameter in the context of our rate-limiting policy." Worth knowing about; not the central concern here.

Documentation maps naturally onto two of the three primitives. Content, the actual text of a documentation page, a reference section, an endpoint description, lives in Resources. Search and query operations over that content, the computation of finding what's relevant to a given question, live in Tools. This is not a provisional recommendation. It follows directly from the primitives' definitions.

Each Tool is defined by a name, a natural-language description, and an inputSchema expressed in JSON Schema. The model sees all three when deciding whether and how to invoke a tool. That structure becomes critical when examining description quality, which is where a surprising amount of documentation exposure fails in practice.

The foundational design decision: when to expose docs as resources versus tools

In practice, the most common question developers ask about MCP documentation exposure is when to use a Resource versus a Tool. The confusion is understandable; the protocol is young, examples are inconsistent across the ecosystem, and MCP clients create real-world pressure that cuts against the correct answer.

The decision rule I've settled on, after working through enough implementations to feel the difference: if the content exists before the conversation starts and doesn't change based on the model's actions, it's a Resource. If the model needs to trigger computation, search an index, or call an external system to retrieve something, that's a Tool.

A first-generation mistake I see repeatedly is exposing everything as Tools. Functions like getapidocs() or getsecuritypolicy() are functionally Resources dressed in Tool clothing. Nothing is computed. Nothing is queried. The content is static and pre-existing. Treating it as a Tool adds architectural complexity with no corresponding benefit. One might argue that the added complexity is a minor inconvenience worth tolerating for the sake of a simpler mental model — but that argument dissolves when you look at what over-tooling actually costs downstream.

The costs of over-tooling go beyond elegance. Every Tool is a potential execution path, which means a larger attack surface. More Tools require more security review: IAM review, risk assessment, architecture approval, compliance sign-off. A server with fifty Tools faces substantially more deployment friction than one with ten Tools and forty Resources. This is not theoretical; it is the actual sequencing of enterprise security review, and it slows down deployment in ways that compound.

The recommended pattern holds: use Resources to hold documentation content, use Tools to expose search and query capabilities over that content. The complication worth naming honestly is that most MCP clients, including Claude Desktop, Cursor, and VS Code, surface Tools prominently in their UI but handle Resources inconsistently. This creates genuine pressure in the other direction. Architects building documentation MCP servers need to consciously resist it, because the cost of over-tooling shows up later, in token budgets, in security reviews, and in attack surface, not immediately in the client interface.

Four concrete patterns for exposing documentation as MCP tool endpoints

Having established when to use Tools versus Resources, the question becomes how to implement the Tool-based query layer. Four patterns have emerged as the practical options.

Pattern 1: Search-as-a-Tool

A single docs_search tool that agents call to retrieve relevant documentation on demand. LlamaBot v0.13.10, released in October 2025, introduced this pattern in a clean form: one tool, agents query it as needed, structured content comes back. The intelligence burden falls on the search index, not on a proliferation of narrowly scoped tools, and the Tool count stays minimal. For teams building from scratch with a well-maintained documentation corpus, this is the pattern I'd reach for first.

Pattern 2: URL-to-endpoint converters

Tools like doc2mcp take a documentation URL, Stripe's API reference, a GitHub README, an OpenAPI spec, a Markdown file, and generate a hosted MCP endpoint automatically. No custom parsers, no bespoke server infrastructure. This pattern is designed for teams that want MCP exposure without building a server from scratch. The trade-off is real: you cede control over how content is chunked, indexed, and described. For a public-facing SDK with well-structured existing documentation, that trade-off is often acceptable. For documentation with complex internal relationships or security-sensitive content, it deserves more scrutiny.

Pattern 3: OpenAPI-to-MCP generation

AWS Labs' OpenAPI MCP Server dynamically generates MCP tools and resources from an existing OpenAPI specification. The mapping is intelligent: GET operations with query parameters become Tools; static data becomes Resources. It automatically enriches tool descriptions with response codes and parameter examples drawn directly from the spec. Mintlify takes a similar approach, generating MCP servers from existing OpenAPI specs via CLI, with automatic coverage of general search and real-time API querying.

This pattern suits teams with a maintained OpenAPI spec particularly well, because the spec does most of the definitional work. The descriptions still need review; auto-generated descriptions inherit whatever clarity or ambiguity was present in the spec. But the structural scaffolding is handled.

Pattern 4: llms.txt + MCP as complementary layers

The llms.txt convention deserves its own treatment because it is frequently discussed as though it competes with MCP. It doesn't. llms-full.txt is a single Markdown-formatted file containing the full text of key documentation pages: a token-efficient snapshot designed for static consumption within a model's context window. LangChain's open-source mcpdoc bridges the two formats, creating an MCP server from a user-defined list of llms.txt files and exposing a fetch_docs tool.

Mintlify benchmarked four documentation serving approaches across 2,400 runs on 20 documentation sites in 2026 and found that a single link to llms.txt eliminates the majority of agent 404 errors at no added token cost. The practical split: llms.txt handles static consumption in a model's context window; MCP handles live querying when current, specific information is needed. Neither replaces the other.

Platform-level tooling

Infrastructure is closing the gap between knowing what to build and being able to build it without excessive friction. GitBook auto-generates MCP servers for published documentation, added llms.txt support in January 2025, and extended that to llms-full.txt and .md page support in June 2025. Mintlify, Stainless, and Speakeasy are all reducing server-creation friction. Cloudflare and Smithery are addressing deployment and scaling. Teams no longer need to start from a blank implementation.

How tool descriptions determine whether agents use the right tool correctly

In MCP workflows, the tool description is the primary semantic interface between a foundation model and a capability. It is how the model decides which tool to select, how to parameterize the call, and how to sequence it within a multi-step task. This is not a soft concern about documentation quality. It is a hard dependency in the agent's decision process.

Each tool's structured definition includes three components the model reads before invoking it: the name (a unique identifier), the description (natural language), and the inputSchema (JSON Schema for parameters). The model weighs all three. The description carries disproportionate weight, because it is where intent is conveyed.

The quality gap across the current ecosystem is striking. A 2025 study found that 97.1% of MCP tool descriptions contain at least one quality issue, with more than half having unclear purpose statements. Even official reference implementations fall short; Anthropic's Filesystem MCP server scored 81 out of 100 in one developer audit, with nearly three-quarters of its parameters carrying no descriptions at all. Why exactly does this happen so consistently, even in implementations maintained by well-resourced teams? Because tool descriptions are written once, at setup, and rarely treated as maintained artifacts — the same documentation debt that plagues API reference prose, concentrated into a format that directly governs agent behavior.

What good looks like, from working through enough of these to have opinions, involves five components: a clear statement of purpose (what the tool does), guidelines for appropriate use (when to invoke it), limitations (what it will not or cannot do), parameter explanation (what each field means and expects), and appropriate length (enough to be unambiguous, no more). A description missing any of these creates gaps the model fills with inference, and model inference under ambiguity defaults toward whatever is plausible, not necessarily whatever is correct.

What bad descriptions cost in practice is concrete: agents pick the wrong tool, mis-parameterize calls, or fall back to doing nothing. The documentation is callable in theory and unreachable in effect. Writing tool descriptions is a distinct skill from writing documentation prose. The audience is different: you are writing for a model's decision process, not for a human's comprehension. Teams that treat tool descriptions as afterthoughts, or generate them automatically from existing documentation without review, will consistently underperform teams that maintain them deliberately.

The token cost of tool definitions and how to keep it manageable

Each MCP tool definition consumes between 550 and 1,400 tokens covering the name, description, JSON schema, field descriptions, enums, and associated system instructions. At scale, this accumulates quickly. GitHub's official MCP server consumes approximately 17,600 tokens of tool definitions per request. Connecting multiple servers can push tool metadata above 30,000 tokens before the agent has processed a single user message.

Scalekit benchmarked MCP against CLI execution across 75 runs on identical tasks and found that MCP cost between 4 and 32 times more tokens per operation depending on the task. A single operation, repository language detection in their benchmark, consumed 1,365 tokens via CLI and 44,026 tokens via MCP. These are not hypothetical concerns for enterprise deployments; they are real operating costs. That raises an important question: if MCP introduces this kind of token overhead, are teams actually net better off using it for documentation exposure? The answer is yes — but only when the architecture is designed to keep tool count low and toolset loading dynamic.

Four mitigation strategies are in production use.

Dynamic toolsets: Load only the tools relevant to the current task rather than registering all tools at session start. Speakeasy's Dynamic Toolset approach achieved an average input token reduction of 96% and a total token reduction of 90% in their 2025 benchmarks.

Search-first discovery: Rather than loading full tool definitions upfront, agents query a tool index to find relevant tools before loading their schemas. StackOne uses this approach across more than 200 connectors and 10,000 actions in production.

Code Mode: Present the MCP server as a code API. The agent writes code to interact with it and processes data in the execution environment before returning results. Only tools needed for the specific code path get loaded.

Protocol-level filtering: MCP Tool Search, introduced in January 2026, detects when tool definitions exceed a threshold portion of the context window and automatically defers loading them until needed.

The design principle these strategies share is worth stating plainly: surface structure should match query scope. A documentation server with a single well-described search tool outperforms one with fifty narrowly scoped tools when token budget is constrained. This connects directly back to the Resources-versus-Tools decision: every piece of documentation content exposed as a Tool instead of a Resource adds to this token burden without contributing to it.

Security risks specific to documentation exposed as MCP endpoints

When documentation is agent-callable, it enters an execution chain. A wrong answer from a static sidebar is an inconvenience. A wrong answer from an agent that can subsequently send emails, call APIs, or write to a database is something else.

Prompt injection is ranked as the number one vulnerability in the OWASP Top 10 for LLM Applications 2025. In MCP environments it can trigger real operations, not just produce incorrect text. Tool poisoning is a related but distinct threat: attackers embed hidden instructions inside tool definitions, the metadata the model reads to decide what to do, manipulating agent behavior at the point of tool discovery.

Invariant Labs demonstrated this concretely in 2025. A malicious MCP server placed in the same agent context as a legitimate WhatsApp MCP server used tool poisoning to silently read and export a user's entire message history. This was not a theoretical demonstration; it was a working exploit. By September 2025, researchers had identified the first known malicious MCP server in the wild: a compromised npm package called postmark-mcp.

The documentation-specific risk surface has two dimensions worth naming. First, documentation content itself can be a vector if user-generated or third-party content is ingested and re-exposed through a tool endpoint without sanitization. An improperly sanitized external documentation source becomes an injection surface at every query. Second, tool descriptions for documentation servers are frequently written loosely, and an imprecise or overly permissive description can be exploited to steer agent behavior toward unintended invocations. It is also worth considering that these two dimensions compound each other: a loosely written tool description paired with unsanitized ingested content creates a much larger exposure than either would in isolation.

Practical mitigations: treat tool descriptions as security-sensitive text and review them accordingly. Validate and sanitize any content ingested from external sources before it enters a tool response. Scope tool permissions to read operations wherever the Resource primitive would appropriately serve instead. Every Tool that can be replaced with a Resource is an execution path removed from the attack surface.

What well-architected documentation-as-MCP looks like end to end

The thread running through this piece has traced a progression: the staleness problem that motivates the architecture, the primitives that frame the design space, the resources-versus-tools decision that determines the foundation, the implementation patterns available, the description quality that determines whether agents use tools correctly, the token constraints that determine whether the server scales, and the security properties that determine whether it's safe to deploy.

A well-architected documentation MCP server integrates all of these. It exposes content as Resources and search operations as Tools, never conflating the two. It minimizes tool count deliberately. GitHub Copilot reduced its tool count from 40 to 13 and measured benchmark improvements. Block rebuilt its Linear MCP server three times, moving from more than 30 tools to 2. The pattern is consistent: fewer, better-described tools outperform more, loosely-described ones.

It writes tool descriptions to the five-component standard, treating them as maintained artifacts rather than one-time setup, reviewed with the same rigor applied to API reference documentation because, in an agent context, that is precisely what they are. It implements dynamic toolset loading or search-first discovery to keep per-request token costs proportional to query scope. It sanitizes ingested content, scopes permissions conservatively, and treats the distinction between Resources and Tools as a security boundary, not merely an organizational preference.

The deeper observation I keep returning to is that everything that makes documentation good for humans, accuracy, currency, clear purpose statements, appropriate scope, becomes structurally load-bearing when that documentation is agent-callable. The craft of documentation was always about reducing friction between a reader and the information they needed. MCP extends the reader to include agents operating at inference time, often on behalf of a developer who will never see the intermediate query. The quality bar doesn't lower when the reader is a model. If anything, it rises, because models cannot tolerate ambiguity the way humans can and will act on whatever they find.