Agent Docs

Agent Docs

An MCP server that gives AI agents the current official documentation of Claude Code, Cursor, Codex and MCP.

These tools change faster than a model's training data. Agent Docs keeps about 600 pages of their official docs in a search index, refreshes it every day, and gives your agent two tools: one finds the right passage, the other reads a whole section. The agent answers from the real docs and can link to them.

It runs as a remote MCP server (and over REST). You can try it with a free Cohere key.

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

The 15 steps as still images

Source and how to rebuild: docs/flow/

How it was built and what was measured: ARCHITECTURE.md.

Connect

Add the server to any MCP client (Claude Code, Cursor, OpenWebUI and others):

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

Calling a tool needs one of two headers:

• Your own Cohere key: X-Cohere-Api-Key: <key>. A free trial key is at dashboard.cohere.com. The key pays for reranking that one request; it is never stored or logged. Limit: 30 requests a minute per IP.
• A token from the owner: Authorization: Bearer <API_TOKEN>. For a guest token, open an issue titled "Guest token request".

The server is on a free plan: after 15 idle minutes, the first request takes about a minute.

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 with -H "X-Cohere-Api-Key: $COHERE_API_KEY".

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

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

For MCP directories: connecting and listing the tools need no key (30 requests a minute per IP); only tools/call does. The server keeps no session, so GET /mcp answers 405; send everything with POST. Listed in the official MCP Registry as io.github.KonstantinStarovoytov/agent-docs (server.json).

What it covers

How it works

Your agent calls search_docs, then read_section when a passage is not enough. No language model runs on the server for this: the agent reads the passages and writes the answer itself.

search_docs works in four steps:

1. It searches by meaning (embeddings) and by exact words (BM25) at the same time, so both "connect a tool server" and claude mcp add find the right page.
2. It merges the two result lists by rank. Ties are kept in a fixed order, so the same question always gets the same results.
3. A reranker (Cohere) reads the top 20 together with the question and scores how well each one matches.
4. It keeps the best passage of each page and adds the page's one-line description and the headings of its other matching sections.

read_section reads from a stored copy of the page; no model is called. Searches are traced in Langfuse.

The REST endpoint /ask is for clients that are not agents. It also translates Russian and Polish questions into English, says "the documentation does not cover this" when even the best candidate scores below 0.55, picks 8 chunks (at most 2 from one section), and has gpt-6-luna write an answer that cites them.

Updated every day

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

The 12 steps as still images

Every day at 06:00 UTC a GitHub Actions job reads each vendor's list of pages (llms.txt) and updates the index:

• Changed pages are embedded again; unchanged ones are skipped.
• New pages are checked first. A suspicious one waits in a GitHub issue until the owner ticks Index or Decline.
• Pages that disappear from the list are deleted, unless too many disappear at once.
• A short report of what changed in the products goes to reports/docs-changes/.

Measured results

Each change was measured on labelled questions before it was kept. All experiments, including the ones that did not work: ARCHITECTURE.md.

When an answer misses part of a question, the search has usually found the right text. It gets lost later, when the candidates are cut down to what the model sees.

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.

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 ruff format --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