Open source · MIT

Open-source Ask AI for your docs.

Cited answers on your own model key, and an MCP server for coding agents, from one index built with your Starlight, Docusaurus or VitePress site. No vendor, no vector database.

Add it to

astro.config.mjs
import ondocs from 'ondocs/starlight';
starlight({ title: 'Acme Docs', plugins: [ondocs()] });

Ask these docs

Live demos

These docs, on real Starlight, Docusaurus and VitePress sites.

Each site is built with its framework’s plugin, and its Ask dialog answers from this site’s endpoint. Open one and ask it something.

Starlight

Built with ondocs/starlight.

ondocs-starlight.vercel.app

Docusaurus

Built with ondocs/docusaurus.

ondocs-docusaurus.vercel.app

VitePress

Built with ondocs/vitepress.

ondocs-vitepress.vercel.app

Set up

One line for Starlight, Docusaurus and VitePress. A script tag for everything else.

Every setup has the same two halves: an index built with your site, and one function that answers from it. The plugins do the first half for you.

A Starlight plugin, and an integration for any other Astro site. It indexes what Starlight’s own search indexes into dist/ask-index.json, and adds the dialog to every page.

  1. Install

    Shell
    npm i ondocs ai @ai-sdk/openai
  2. Add the plugin

    JavaScript
    // astro.config.mjs
    import starlight from '@astrojs/starlight';
    import ondocs from 'ondocs/starlight';
    import { defineConfig } from 'astro/config';
    
    export default defineConfig({
      integrations: [starlight({ title: 'Acme Docs', plugins: [ondocs()] })],
    });
  3. Deploy as you do now

    With an SSR adapter, the integration serves the ask and MCP endpoints itself: there is no file to write. A static site writes its endpoint with npx ondocs init. Astro with an adapter

For agents

The same index, for the agents that read your docs.

Coding agents and AI apps search and read your docs over MCP, with their own model. Search is keyword-only by default, so it calls no model at all. Connect yours to these docs:

These docs are an MCP server at https://ondocs.vercel.app/api/mcp. Connect your AI tool to it, and its agent can search and read them.

Claude Code:

Shell
claude mcp add --transport http ondocs https://ondocs.vercel.app/api/mcp

Codex:

Shell
codex mcp add ondocs --url https://ondocs.vercel.app/api/mcp

Gemini CLI:

Shell
gemini mcp add --transport http --scope user ondocs https://ondocs.vercel.app/api/mcp

ChatGPT: add a custom MCP server with this URL at chatgpt.com/plugins.

Other clients
JSON
{
  "mcpServers": {
    "ondocs": {
      "type": "http",
      "url": "https://ondocs.vercel.app/api/mcp"
    }
  }
}

Codex, in ~/.codex/config.toml:

TOML
[mcp_servers.ondocs]
url = "https://ondocs.vercel.app/api/mcp"
search({ query: "GitHub Pages without an API key" })
{
  "results": [
    {
      "id": "/docs/workers-ai",
      "title": "Workers AI, without an API key",
      "heading": "",
      "url": "https://ondocs.vercel.app/docs/workers-ai",
      "text": "A docs site on GitHub Pages, S3, Read the Docs or any other host that only serves files can have its Ask box and its MCP endpoint answered by a Cloudflare Worker with Workers AI, Cloudflare's own models.…"
    }
  ]
}
What an agent gets back: the first of the 8 sections this site’s MCP server found, asked while the page was built.

search and fetch

Ranked sections with a snippet and a link to the anchor, then the page or section as Markdown: the shape ChatGPT’s connectors expect, over MCP 2026-07-28 and 2025-11-25.

llms.txt and .md pages

The plugins also write llms.txt, llms-full.txt and a Markdown copy of every page, and leave alone what another llms plugin writes.

Add to Cursor, VS Code, Claude

With the plugins’ mcp option, a docs page shows the install links and the Claude Code command for your endpoint.

The MCP server

How it works

Indexed when you deploy. Searched in memory when someone asks.

Docs change when you deploy, not between requests, so the index is a file built with the site instead of a database kept in sync with it.

Build time once per deploy

CLI or framework pluginondocs indexReads your Markdown, MDX or built HTML. Splits it at every heading, embeds each chunk and quantizes the vectors to int8.
Static fileask-index.json1.6 MB per 1,000 chunks, deployed with the site.

Rebuilt on every deploy, re-embedding only the chunks whose text changed. --check fails CI when a committed index is stale.

Request time per question

VisitorAsks a questionIn the dialog, or your own UI with useAsk.
Relevance gateAnything relevant?Cosine ≥ 0.25, or keyword coverage ≥ 0.5.
YesStreamed answer, cited 12Written by your model, from the sources only.
No“I don’t know”Streamed at once. The model is never called.

Keywords and meaning

BM25 finds exact names like createAskHandler and error codes; vectors find paraphrases. Reciprocal rank fusion merges the two rankings by rank alone.

A gate before the model

Most off-topic questions get “I don’t know” before the model is called, fast and free. One that shares enough words with your docs can still reach it, and the model is told to answer from the sources alone.

Citations that land

Pages are split at every heading, so 1 opens the section an answer came from, at the URL your framework serves.

How retrieval works

Numbers

Measured, at the sizes a docs site has.

1.6 MBindex for 1,000 chunks
int8 vectors in base64; 0.9 MB gzipped. The same index as float JSON is 7.5 MB.
0.71 msmedian query over 1,000 chunks
BM25, cosine scan and fusion, in memory. 6.96 ms at 10,000 chunks.
3.6 KBscript tag on each page, gzipped
The button and shortcut. The dialog loads the first time it is wanted.
22 / 22agent-style searches we wrote, with the right page in the top three
On docusaurus.io’s own docs, keyword-only: no model call. Checked in CI. The queries
20 / 22the same needs, asked as a person asks
Questions we wrote too. Real Stack Overflow and GitHub questions, in their own words, find the right page far less often.
≤ 800output tokens per answer, by default
With at most 8,000 characters of sources in: one embedding call and one model call.

From pnpm bench on an Apple M1 Max with Node 24.18: synthetic, documentation-shaped corpora with 512-dimension vectors, 1,000 queries per size. Query times exclude the embedding API call. All results

Compared

A local index like Pagefind’s, plus cited answers. No cloud account.

Hosted assistants, ondocs and search-only tools compared
Hosted assistantsKapa, Inkeep, Algolia Ask AI, Biel.aiondocsA library, on your infrastructureSearch onlyPagefind, Orama’s local index
What a visitor getsWritten answers with citationsWritten answers citing the exact sectionA list of matching pages
Where your docs are indexedOn the vendor’s platformA static file in your buildStatic files in your build
What you runNothing, it is hostedOne function: Vercel, Netlify, Cloudflare or any Request → Response runtimeNothing
Model and keyThe vendor’s (Algolia Ask AI: yours)Yours, through any AI SDK providerNone
Account and pricingA vendor account and planNone. You pay your model provider per questionNone
For agentsHosted MCP on most plansYour own MCP endpoint and llms.txt; by default, agent search calls no modelNo
Follow-up questions and dashboardsTypically includedFollow-ups, yes. No dashboard: log questions with onFinishNo

When it’s the wrong tool

  • Past about 50,000 chunks. Search is an exact scan; at that size an approximate index or a vector database is better.
  • Content that changes per user or per request. The index is rebuilt when you deploy.
  • Multi-turn chat with a dashboard, and nothing to run. A hosted assistant does that.
  • Search results with no server at all. Use Pagefind.
Limits and trade-offs

Add it to your docs.

Try it on your own content in two minutes, without an API key: index with the mock model and run npx ondocs dev.

Terminal
$ npm i ondocs
$ npx ondocs index ./docs -e mock
$ npx ondocs dev