How Do I Make My Docs Usable Inside AI Agents?
For Developer documentation maintainers · Based on Rachel Lee's Agentic Web Publishing Framework
// TL;DR
If you maintain developer documentation — API references, guides, tutorials — this framework lets coding agents like Claude and Copilot access your docs directly inside their interfaces. Map your docs navigation to MCP tools (list_guides, search_docs, list_api_methods), serve bulk content via MCP Resources for context priming, and add Web MCP to your HTML pages so in-browser agents can navigate sections and pull examples without screenshot-based guessing. Your docs site keeps working normally for browser users.
Why Can't AI Coding Agents Use My Docs Today?
Most documentation sites are built for humans in browsers. When a developer asks Claude or Copilot about your library, the agent either has stale training data or must scrape your site through screenshot-based DOM traversal — slow, expensive, and unreliable. Rachel Lee's Agentic Web Publishing Framework solves this by making your docs a first-class data source inside agent harnesses.
The core idea: your documentation already has a navigation structure — guides, API methods, search, examples. Each of these maps directly to an MCP tool. You don't rebuild your docs site; you add an MCP server alongside it.
How Do I Map My Docs to MCP Tools?
Start by auditing your docs navigation. A typical documentation site has:
- List actions: list all guides, list API methods by category
- Search: full-text search across docs
- Detail views: individual guide pages, method reference pages
- Examples: code snippets and usage patterns
Each becomes an MCP tool. `list_guides` returns JSON with titles, slugs, and summaries. `search_docs` accepts a query string and returns ranked results. `get_guide` returns Markdown for a specific guide — not an MCP App, because developers working in agents want text they can copy and reference, not an interactive widget.
For your full documentation corpus, use MCP Resources rather than tools. Resources let agent harnesses pre-prime context when a developer switches to your library's mode, instead of making the agent call tools one chunk at a time and burning context window.
Choose HTTP transport for your MCP server. Host it at `/mcp` on your docs domain. Developers paste one URL into their agent settings and gain immediate access to your entire docs surface.
How Do I Support In-Browser Agents on My Docs Pages?
For developers using in-browser agents (agents operating within the browser itself), add Web MCP registration to your HTML pages. Use the imperative model:
```javascript
if (navigator.modelContext) {
navigator.modelContext.registerTool(
'navigate_to_section',
'Jump to a specific section of the current documentation page',
{ type: 'object', properties: { sectionId: { type: 'string' } } },
(params) => scrollToSection(params.sectionId)
);
navigator.modelContext.registerTool(
'get_example',
'Get the code example for this API method',
{ type: 'object', properties: { methodName: { type: 'string' } } },
(params) => getExampleCode(params.methodName)
);
}
```
The callback functions are the same ones your UI already uses. The agent calls them directly instead of guessing from screenshots. Always wrap registration in an `if (navigator.modelContext)` check so non-agent browsers degrade gracefully.
What Mistakes Should I Avoid?
The biggest mistake is using MCP tools to serve your entire docs corpus one call at a time. This burns context window fast. Use MCP Resources for bulk priming and tools for targeted lookups.
Don't default to stdio transport. Your docs serve a broad developer audience — HTTP transport means zero config-file friction. And don't over-expose tools: match your tool count to your navigation structure, not your internal function count.
Finally, test across all three client types: verify your docs site still works in a browser, install your MCP server in Claude Desktop to confirm tools return correct data, and use the MCP B extension to validate Web MCP registration on each page.
Next step: Audit your docs site's navigation right now. List every action a developer takes — that list is your MCP tool surface.
// FREQUENTLY ASKED QUESTIONS
Do I need to convert my whole docs site to work with this framework?
No. Your docs site keeps working normally for browser users. You add an HTTP MCP server alongside your existing backend that maps your docs navigation to tools. Optionally add Web MCP registration to your HTML pages for in-browser agents. The framework augments your docs — it does not replace them.
Should I return MCP Apps or Markdown from my docs tools?
Return Markdown for text-rich content like guides, API references, and tutorials — developers in agents want copyable, referenceable text. Reserve MCP Apps for interactive content like visual API explorers, interactive examples, or diagram-based architecture docs where a static text response would be insufficient.
How do I handle versioned documentation with MCP tools?
Add a version parameter to your tool input schemas (e.g., list_api_methods accepts a version string). Default to the latest version if not specified. Your MCP server routes to the correct version of the documentation. This mirrors how your docs site already handles versioned URLs — the same backend logic applies.