Agent Docs MCP Server

Agent Docs

Ask questions about Claude Code, Cursor, Codex and MCP — get answers grounded in their official docs, with citations.

A hybrid RAG service that AI agents call through two MCP tools (or over REST). It indexes ~600 pages of official documentation, refreshes itself daily, and every design choice is backed by an experiment.

Why it is built this way, what was tested, and a glossary of every term: ARCHITECTURE.md

Step through it at your own pace (arrow keys work), or open the stills:

Source and how to rebuild: docs/flow/

---

How it works

Your agent calls a remote MCP server with two tools: search_docs, then read_section when a passage is not enough. No model runs on this path; the agent writes the answer itself. The animation at the top walks through it.

The /ask REST endpoint, for clients that are not agents, adds a few steps after the rerank:

search_docs stops after the rerank and returns the best passage of each page, so one long page cannot fill the list. Each passage carries the page's one-line description and the headings of the page's other matching sections (other_sections). The agent reads the passages itself, which is cheaper; for a longer read, read_section returns a page's outline, then one section's text from the stored page (no model call). Searches are traced in Langfuse; read_section, which calls no model, is not.

Fresh every day

Step through it at your own pace, or open the stills:

New pages are indexed automatically; suspicious ones wait for a human. Each run writes a short report of what changed in the products: reports/docs-changes/.

What it covers

---

Connect

Connecting and listing the tools needs nothing: every MCP message except tools/call answers without a key (30 requests/min per IP), so MCP directories can check the server. The server is stateless, so GET /mcp answers 405; send everything with POST. Calling a tool needs one header, either of:

• Your own Cohere key: X-Cohere-Api-Key: <key>. A free trial key is at dashboard.cohere.com. Reranking runs on your key; the key is used for that request only and never stored or logged. Limit: 30 requests/min per IP.
• A token from the owner: Authorization: Bearer <API_TOKEN>.

As an MCP server (Claude Code, Cursor, OpenWebUI, any MCP client):

{
  "mcpServers": {
    "agent-docs": {
      "url": "https://agent-docs-mcp.onrender.com/mcp/",
      "headers": { "X-Cohere-Api-Key": "<your Cohere key>" }
    }
  }
}

REST also offers /ask (a written answer with citations) and /pages (page cards) for clients that are not agents.

Over REST:

curl -X POST https://agent-docs-mcp.onrender.com/ask \
  -H "Authorization: Bearer $API_TOKEN" -H 'content-type: application/json' \
  -d '{"question": "How do I add an MCP server in Claude Code?"}'

With your own key, replace the Authorization line in the curl with -H "X-Cohere-Api-Key: $COHERE_API_KEY".

Try it. The quickest way is your own free Cohere trial key (above), limited to 30 requests a minute per IP. Or open an issue titled "Guest token request" for a shared guest token. The first request after 15 idle minutes takes about a minute while the free host wakes up.

Listed in the official MCP Registry as io.github.KonstantinStarovoytov/agent-docs (server.json).

Locally, without a server (stdio, no token):

{ "mcpServers": { "agent-docs": { "command": "uv",
  "args": ["run", "--directory", "/path/to/agent-docs", "rag-mcp"] } } }

---

Where it runs

Deploys run only after CI passes. The whole service is defined in render.yaml.

Deploy your own: Render → New → Blueprint → this repo. Fill the secrets it asks for (OPENAI_API_KEY, COHERE_API_KEY, optional COHERE_API_KEY_FALLBACK, QDRANT_URL, QDRANT_API_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY); API_TOKEN is generated for you. If you change the host name, update API_ALLOWED_HOSTS (the MCP transport rejects unknown hosts). Revoke a guest by clearing API_GUEST_TOKEN.

Cost

Limits of the free setup: Cohere trial allows 1,000 reranks/month per key (two keys) and 10/minute; the API is capped at 60 paid requests/minute.

---

Key results

Main finding: search finds the right page; the hard part is choosing what the model sees. Details and every experiment: ARCHITECTURE.md.

---

Develop

uv sync --locked                      # Python 3.14
cp .env.example .env                  # OpenAI, Cohere, Qdrant, Langfuse keys
docker compose up -d                  # local Qdrant + API on :8080
uv run python -m src.ask "How do skills work?"
uv run pytest -q && uv run ruff check src evals tests && uv run mypy

Re-index locally: uv run python -m src.reindex --dry-run --out /tmp/r (no writes) — or run the Reindex workflow in GitHub Actions.

Diagrams: edit docs/diagrams/*.mmd, then uv run python scripts/render_diagrams.py. Animations: edit docs/flow/flows/ask.js (a question) or docs/flow/flows/reindex.js (the daily reindex), then docs/flow/render.sh.

License

MIT