DEV Community: Anton Malling

How to Give AI Coding Agents Access to Your Product Docs

Anton Malling — Tue, 07 Jul 2026 11:05:40 +0000

Short answer: You give AI coding agents access to your product docs by exposing your documentation through an MCP server or a retrieval API, then registering it as a tool in the agent. Once connected, tools like Claude, Cursor, Codex, and VS Code query your current docs and code at the moment they need them, instead of guessing from stale pretraining data or generic web search. Kapa.ai does this with a one-click hosted MCP server and a Retrieval API, so agents answer from your live documentation with citations.

Key takeaways

Coding agents get your product wrong because your docs, APIs, and changelogs are not in their training data.
The Model Context Protocol (MCP) is the open standard for connecting agents to external knowledge; a retrieval API is the alternative for custom builds.
A hosted MCP server means no infrastructure to run: connect sources once, register one URL in the agent.
Grounding an agent in your docs also makes its other tools sharper, because it finally understands your product.
Accurate retrieval is the differentiator; kapa.ai returns the right source roughly twice as often as web search or a DIY RAG pipeline.

Why do AI coding agents get your product wrong?

AI coding agents get your product wrong because the answer is not in the model and not in your APIs, it lives in your docs, code, changelogs, and support tickets. Your users work in Claude Code, Cursor, and Codex, and those agents fall back on outdated pretraining data or generic web search when they hit a product-specific question. So when someone asks "how do I enable SSO?" or "why did my deploy fail?", the agent has no tool for it and guesses.

That guessing is the most common failure mode in production agents. The fix is to give the agent a way to retrieve your current product knowledge on demand, so it answers from your documentation instead of its memory.

How to give AI coding agents access to your docs

You connect your docs to an agent by exposing them as a tool the agent can call, using either an MCP server or a retrieval API. Both approaches let the agent run a semantic search over your knowledge base mid-task and pull back the relevant, cited content:

MCP server: the standard choice for connecting off-the-shelf coding tools (Cursor, Claude, VS Code, and others). You register one URL and the tool can query your docs.
Retrieval API: a plain HTTP call for teams building their own agent with a framework like LangGraph, OpenAI Agents, or an in-house orchestrator.

In both cases, the agent's native tools keep handling your product's actions (queries, mutations, object creation), while the docs-search tool supplies the product knowledge it needs to use those tools correctly.

What is MCP, and which coding tools support it?

MCP (Model Context Protocol) is an open standard from Anthropic that lets AI agents connect to external tools and data sources, like a universal API for AI assistants. An MCP server exposes your documentation so any MCP-capable tool can query it directly. Support is broad across the coding tools your users already run:

Tool	How MCP is added
Claude Code	`claude mcp add` in the terminal
Claude Desktop	Settings > Custom Integrations, or config file
Cursor	`.cursor/mcp.json` or Settings > MCP
VS Code (Copilot)	`.vscode/mcp.json`
ChatGPT Desktop	Settings > MCP Servers (developer mode)
Codex	`codex mcp add`
Windsurf, Zed, Antigravity	MCP config file

Setup: connect your docs in a few steps

With a hosted MCP server, giving agents access to your docs takes four steps and no infrastructure to run. Using kapa.ai as the example:

Connect your sources. In the dashboard, add your docs, code, PDFs, tickets, Slack, and any of 30+ sources; kapa.ai builds them into one synced knowledge base.
Add the integration. Add a Hosted MCP Server (or use the Retrieval API for a plain HTTP call), and set a subdomain, server name, and authentication.
Wire it into your agent. Copy the MCP URL and register it as one tool alongside the agent's existing tools. That is the whole change.
Ship it. The agent now falls back to your docs whenever its own tools cannot answer, and cites the source.

Because the server is remote and hosted, your users install nothing: they paste one connection URL into their AI tool. Building your own MCP server, by contrast, means running infrastructure, managing auth and rate limits, and ongoing maintenance.

MCP server vs Retrieval API: which should you use?

Use a hosted MCP server to connect existing coding tools, and the Retrieval API when you are building a custom agent. They expose the same underlying semantic search over your knowledge base.

	Hosted MCP server	Retrieval API
Best for	Off-the-shelf tools (Cursor, Claude, VS Code)	Custom agents (LangGraph, OpenAI Agents, in-house)
Integration	Register one URL	Plain HTTP call
Infrastructure	Fully hosted, one click	You orchestrate the calls
Users install	Nothing, paste a URL	N/A, server-side

How accurate is agent retrieval, and why does it matter?

Retrieval accuracy is what decides whether grounding actually helps, because a wrong chunk sends the agent back to guessing. On real product questions, kapa.ai's agentic retrieval returns the right source almost twice as often as general web-search APIs or a DIY RAG pipeline. The benchmark is Recall@5 across four real customer projects (developer tools, semiconductors, software platforms), 30 human-annotated multi-source production questions each, with web search using site limiters for fairness and DIY pipelines built on Azure AI Foundry and Firecrawl plus Pinecone.

The payoff compounds: an agent that retrieves the right context not only answers knowledge questions correctly, it also uses its other tools more accurately, because it finally understands your product.

How Kapa.ai gives your agents product knowledge

Kapa.ai gives AI coding agents your product knowledge through a one-click hosted MCP server and a Retrieval API, grounded in a single synced knowledge base. You connect docs, code, PDFs, tickets, and 30+ sources once, everything stays in sync so answers are never stale, and every answer is cited. It works out of the box with Cursor, Claude, VS Code, Codex, and other MCP clients, and teams like Port, Airbyte, Matillion, and Nordic Semiconductor already build coding assistants, product copilots, and support agents on it.

How we index images for RAG

Anton Malling — Mon, 08 Jun 2026 18:11:25 +0000

kapa.ai builds AI documentation assistants, an LLM-powered RAG chatbot for technical documentation used in production by 200+ technical companies. The knowledge bases we process hold millions of images like screenshots, architecture diagrams, circuit schematics, annotated UI walkthroughs. We spent several months working out how to make them useful in our RAG pipeline.

The short version: we don't send images to the model at query time. We describe each image once, at indexing time, with a cheap vision model, store the descriptions as text, and retrieve them alongside ordinary text chunks. Indexing is a one-time cost; after that, per-query overhead is 1% to 6% over text-only, and answers are measurably, statistically significantly better. This post explains how we got there.

Both answers are correct. The one that shows the screenshot is the one a user can act on without hunting for the setting.

What images actually do in technical documentation

We went through thousands of real customer questions across hardware, semiconductor, and developer-tooling accounts to see how images earn their place in an answer. They split into two kinds.

Most are illustrative. They show what the text already says, only more clearly: a guide says "click the settings icon," and the screenshot beside it shows which icon, where, and what it looks like. The words carry the fact; the picture makes it easy to act on.

Some are load-bearing. A wiring diagram, a spec table, a certification or color-availability matrix can hold a value that lives in the figure and essentially nowhere else. There the picture is not a convenience, it is the source of the answer.

We confirmed the lift either way: with image context available, an LLM judge preferred the answers across three customer projects and two models, by a statistically significant margin (McNemar's test, p < 0.05).

The improvement is the kind a user feels. Instead of "look for the configuration section that controls the setting," you get the specific path plus a screenshot showing exactly where to click. Same facts, far easier to act on. For a support assistant, that is the difference between a user who self-serves and one who opens a ticket.

Either way, images make answers materially better. The engineering question is the one the rest of this post is about: how to use them without paying a vision bill on every query.

Why query-time multimodal does not work at scale

The approach most people reach for first: retrieve the relevant chunks, collect the images they reference, and pass everything to a vision-capable model.

We tested it with GPT 5.1 and Claude 4.6 Sonnet across hundreds of production questions. The problems are structural, not engineering details to tune away.

The economics do not work. Raw images added 27% to per-query cost on GPT and 51% on Claude (Claude tokenizes an image at roughly 975 tokens to GPT's 716). We serve millions of queries; paying that much more on all of them, when most answers do not need a fresh look at the pixels, is not a trade we can make.

The images do not physically fit. A typical question retrieves 10-30 chunks referencing 20-30 images on average, with a long tail past 130. Claude's payload limit is 30 MB and OpenAI's 50 MB; around 25 images already approaches Claude's ceiling. You would have to cap images aggressively, which defeats the point.

Multimodal retrieval does not suit this domain. CLIP-style embeddings wash out exactly the fine detail that matters in charts, tables, and annotated screenshots, and short technical queries ("how do I configure X") give too little signal to match against image vectors.

These are properties of today's ecosystem, not bugs to fix. They pointed us away from query-time vision entirely.

Describe once at indexing time, retrieve as text

The approach that works inverts the economics. Instead of paying to process images on every query, you pay once, at indexing time, to turn each image into a text description. After that, retrieval and generation run entirely in text.

At indexing time, a vision language model writes a caption for each image. The captions are stored and retrieved alongside ordinary text chunks. At query time, if a caption is relevant, the retriever pulls it in; the model sees the caption, never the raw image, and cites the image by its original URL.

This works because the heavy lifting, actually looking at the image, happens once, at ingestion, instead of on every query. For an illustrative screenshot the caption is a description; for a load-bearing figure it is a transcription of what the figure holds, the values in the table, the labels on the diagram. Either way the content becomes text, and the rest of the pipeline never has to see a pixel. Microsoft's research team also reached the same conclusion: describe at ingestion, store as separate chunks.

This is what makes the load-bearing case work, and it is where a lot of assistants quietly fail. A color-availability matrix is a wall of check marks; a fire-resistance table is a grid of ratings. Flatten one into plain text with a generic extractor and the structure dissolves, which is how an assistant ends up confidently telling a customer a panel comes in a color it does not. Transcribed at ingestion, the same matrix becomes retrievable text, and the answer stays grounded in what the figure actually shows.

For datasheet-heavy products, the figure can sometimes be the answer. Though, this is rarely found based on real user questions in production.

What you have to get right in production

Filtering: most images are junk, and some cannot be classified

You cannot caption millions of images indiscriminately. Most are noise: logos, avatars, social preview cards, decorative banners. Heuristics handle the first pass (drop unsupported formats, tiny images, extreme aspect ratios). For the rest, we built a zero-shot classifier on multimodal embeddings. It is cheap enough to run across the whole corpus.

On clear-cut images it hits 96.8% accuracy (F1 0.974). On ambiguous ones, accuracy collapses to 59.8%, and the reason is fundamental. A screenshot of a countdown timer could be a decorative banner or step 3 of a tutorial about timers. The pixels are identical; without the surrounding text there is not enough information to decide, and no embedding model can fix that. So we accept it: the classifier removes the clear junk (about 13% of what survives heuristics) and we tolerate the ambiguous edge. Context-aware classification is the obvious next step.

Captioning: context matters more than model size

Two things drive caption quality. First, surrounding text: feed the model the paragraphs before and after the image and quality jumps. Without context, a file-upload dialog is "a web page with a file upload form"; with it, the caption is grounded in the specific product, workflow, and step, which is what makes it useful for retrieval.

Second, expensive models buy little. We compared five, from Claude 4.6 Sonnet down to GPT 5.4 nano. A small model (GPT 5.4 mini) produced captions almost indistinguishable from models four times its price; only nano dropped off. At our scale, a small model is the obvious choice.

Storage: separate caption chunks beat inline

Two ways to integrate a caption. Inline: replace the image's alt text in the document, so some chunks carry both text and description. Separate: store each caption as its own chunk, leaving the document untouched.

We expected inline to win, since the caption sits next to its text. Separate won, on both cost and image usage. Inline captions inflate every chunk they live in, and those chunks ship on every query whether the images are relevant or not. Separate chunks only enter the context when the retriever judges them relevant, so you pay for an image only when it matters. On one image-heavy project, inline raised per-query cost 19% with GPT; separate, 6%. With Claude, separate captions slightly lowered cost versus text-only. And they earn their place: the re-ranker promoted them into the top 15 on 51% of queries, while overall ranking held steady (Spearman ρ = 0.905).

Results

End to end across three customer projects with GPT 5.1 and Claude 4.6 Sonnet:

	Text-only baseline	With image captions
Images cited in answers	0%	10% to 64%
Answer quality (LLM judge)	baseline	significantly better (p < 0.05)
Per-query cost	baseline	+1% to 6%
Latency (time to first token)	baseline	sub-second increase
Model uncertainty	baseline	unchanged or slightly lower
Indexing cost	n/a	one-time, then no recurring image cost

Across every experiment, images were placed correctly 94% to 99% of the time.

This is a less flashy answer than "use a multimodal model," and that is the point. It works because it puts the vision where it belongs: once, at ingestion, turning whatever an image holds into text, instead of paying to re-examine pixels on every query. Whether an image clarifies the words or carries the answer outright, reading it once is cheaper and a better fit for how the rest of the pipeline works. The constraints we hit were not obstacles to engineer around; they were pointing at the architecture.

This ships into kapa's answer engine as part of how we keep answers accurate on real-world technical docs, where the diagram or the spec table is often where the answer actually lives. Rolling out in preview now.

Written by the team at kapa.ai, an LLM-powered RAG chatbot for technical documentation used by 200+ technical companies including N8N, Grafana, Sentry and Nokia. This post was originally published at kapa.ai/blog/how-we-index-images-for-rag.

We shipped 30 tools to our agent. The most-used one just reads our documentation.

Anton Malling — Mon, 08 Jun 2026 17:55:51 +0000

The most important tool in our product agent is the one that reads documentation

A few months ago we shipped an agent inside our own product. It lives in our web app and our customers use it to ask questions about their deployment - things like "how many Slack bot questions have users asked in the last month?".

We built the agent because the analytics tooling we'd shipped (clustering, tagging, filters) never quite covered every use case, and we wanted to see if a chat interface could.

For context, the agent has around 30 native tools to interact with our platform like search_conversations, display_chart, and so on.

And the agent also has a single search_knowledge_base that can read our documentation, code examples, support FAQs and API reference.

We expected the native tools to do most of the work.

But when looking at the last 1,192 conversations we found that search_knowledge_base was the most used tool, almost as much as all the native tools combined.

This post is about what we found when we looked at why.

Finding #1: Documentation became the fallback

The main use case for knowledge base search was acting as a failover for the agent when users asked questions that no native tool calls could help with. That accounts for 32.1% of conversations.

These were conversations where users asked completely reasonable product questions like:

"How do I set up the Slack integration?"

"Why am I getting CORS errors on the widget?"

"How often do website crawls ingest?"

If we had shipped with native tools but no search_knowledge_base, the agent would have had to refuse or guess.

What happened here is we had built an analytics agent but our users treated it as a "catch-all" product agent.

Finding #2: Documentation adds context to the native tools

The next pattern was conversations where the agent used both kinds of tools. Around 7% of the total.

These were smaller in volume but they made the division of labor between the two kinds of tools clearer than anything else. The native tools answer what is true about the user's account right now. search_knowledge_base answers what it means.

A representative example: a user asked what type of MCP integration they had set up and how it differed from the other options. list_integrations answered the first half - here's what you have configured.

To answer the second half the agent needed to read the docs, because the comparison between integration types lives there.

Neither tool could have answered this on its own. The native tool knew the state. The knowledge-base tool knew the product.

The answer required both. This is the role most people probably expect a docs-reading tool to play in an agent. It's real, it matters, and it was the smallest of the three patterns we found.

Finding #3: Documentation helps the agent use its own tools

This was the most interesting pattern and the one we didn't expect.

In some conversations, search_knowledge_base wasn't being called to answer the user. It was being called so the agent could figure out what to do.

The clearest example: a user asked the agent to find conversations with negative sentiment. We don't have a sentiment filter. We don't have a "sentiment" field anywhere in the product. An agent with only native tools would either refuse or guess at a tool that doesn't exist.

What our agent did instead was search the documentation, find that we capture negative signals as downvotes and feedback comments, and then call the right native tool with the right filters.

The docs weren't the answer. They were the briefing the agent needed before it could act. Instead the knowledge-base tool was doing planning work.

We've started thinking of this as a third job the knowledge-base tool does, alongside answering and contextualizing: it teaches the agent what the product can actually do, so the agent can pick the right native tool.

So what

If you're building a product agent, the knowledge-base tool is a lot more important than you might think.

It catches the questions your native tools were never designed for, which will be more of them than you think. It explains what your native tools return when the raw output isn't enough. And it tells the agent which native tool to call when the user's language doesn't match your schema.

We shipped 30 native tools and one tool that reads documentation. The one that reads documentation is what makes the other 30 useful.

Built by the team at kapa.ai - an AI documentation assistant for technical docs used by teams like Nokia, Grafana and Sentry.