rag-context-assembly

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

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.

_{Diagram source: docs/diagrams/readme-how-it-works.mmd}

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. 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). Every request is traced in Langfuse.

Fresh every day

_{Diagram source: docs/diagrams/readme-daily-refresh.mmd}

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

Two ways in, one header each:

• 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/rag-context-assembly", "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.