Lets AI agents search, fetch, and list pages from your documentation using a static index and MCP server.
Also known as dgesteves/ondocs, docusaurus-plugin-ondocs, starlight-ondocs
- Stars
- 11
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is ondocs MCP?
ondocs lets AI agents search, fetch, and list pages from your documentation using a static index and MCP server.
Summary generated from the project's README
About ondocs MCP server
ondocs provides an open-source way to add AI-driven search and retrieval to documentation sites. It is designed for teams running developer documentation through platforms like Starlight, Docusaurus, or VitePress. Instead of relying on a hosted assistant or a separate vector database, it uses a static index file called ask-index.json to power both a user-facing chat interface and an MCP server for coding agents.
Developers can integrate this by adding specific plugins to their site builds or using a script tag for plain HTML sites. The MCP server enables tools like search, fetch, and list_pages, allowing agents in editors such as Cursor, VS Code, or Claude Code to access documentation directly. Users provide their own model keys from providers like OpenAI, Anthropic, or Google Gemini, or they can use Cloudflare Workers AI for a keyless setup. The system uses BM25 and vector search merged with reciprocal rank fusion to ensure high-quality results without needing a complex backend infrastructure.
What you can do with it
- 1Add an interactive chat boxProvide a dialog box on your website that answers user questions with citations from your docs.
Written from the project's README. Every use case is checked against a quote from it.
How to install ondocs MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ondocs MCP in Claude Code
$ claude mcp add ondocs -- npx -y docusaurus-plugin-ondocsInstall ondocs MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ondocs": {
"command": "npx",
"args": [
"-y",
"docusaurus-plugin-ondocs"
]
}
}
}Install ondocs MCP in VS Code
.vscode/mcp.json
{
"servers": {
"ondocs": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"docusaurus-plugin-ondocs"
]
}
}
}Install ondocs MCP in VS Code CLI
$ code --add-mcp '{"name":"ondocs","type":"stdio","command":"npx","args":["-y","docusaurus-plugin-ondocs"]}'Install ondocs MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ondocs": {
"command": "npx",
"args": [
"-y",
"docusaurus-plugin-ondocs"
]
}
}
}Install ondocs MCP in Codex
$ codex mcp add ondocs -- npx -y docusaurus-plugin-ondocsInstall ondocs MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.ondocs] command = "npx" args = ["-y", "docusaurus-plugin-ondocs"]
Install ondocs MCP in Gemini CLI
$ gemini mcp add -s user ondocs npx -- -y docusaurus-plugin-ondocsInstall ondocs MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ondocs": {
"command": "npx",
"args": [
"-y",
"docusaurus-plugin-ondocs"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledgesteves/ondocs is public and reachablegithub.com/dgesteves/ondocs ↗Pass
- Package names this repository as its sourcedocusaurus-plugin-ondocs, ondocs name dgesteves/ondocs as sourcenpmjs.com/package/docusaurus-plugin-ondocs ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for docusaurus-plugin-ondocs, ondocsnpmjs.com/package/docusaurus-plugin-ondocs/v/0.18.0#provenan ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/dgesteves/ondocs ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from docusaurus-plugin-ondocs, ondocs, starlight-ondocsPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubondocs
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.
For teams that run their own developer docs, at product, API and platform companies, who want Ask AI without a hosted assistant.
Ask these docs from your editor, over this site's MCP server:
Website: ondocs.vercel.app, whose docs answer with OpenAI and serve agents at /api/mcp. Formerly ask-my-site (what changed).
Feedback wanted: say where it breaks in the launch feedback thread, see what's next in the roadmap, or pick up a good first issue. If ondocs is useful to you, a star helps other people find it.
https://github.com/user-attachments/assets/6922d183-beeb-4c0b-bea3-2e1aba1eee56
The live demo: a streamed answer with citations, one opening the section it came from, then the one-line setups.
Live demos: Starlight, Docusaurus and VitePress, each a real docs site built with its plugin.
What you get
One index, ask-index.json, built with your site, feeds three things:
- An Ask box for people. A ⌘I dialog that streams a short answer from your model, with numbered citations to the exact section. Most off-topic questions get "I don't know" before the model is called. A page loads only the button; the dialog loads on first use.
- An MCP server for agents.
search,fetchandlist_pagesover the same index, for coding agents and ChatGPT. Agents bring their own model, and keyword search, the default, calls no model at all. llms.txt,llms-full.txtand a.mdcopy of every page, written with the build.
Search runs in memory inside one function you deploy: BM25 and vectors, merged with reciprocal rank fusion.
Pick your setup
| Your site | What you add | Guide |
|---|---|---|
| Starlight, or any Astro site | A plugin, or an integration | Astro and Starlight |
| Docusaurus 3 | A plugin | Docusaurus |
| VitePress | One wrapper in its config | VitePress |
| Next.js or another React app | A route and a component | Next.js and React |
| Fumadocs | A route and a component | Fumadocs |
| Nextra | A route and a component | Nextra |
| Hugo, Jekyll, MkDocs or plain HTML | One script tag; for plain HTML, init --out <dir> |
Script tag |
Each answers from an endpoint you deploy as one function next to the site, rate-limited by default. npx ondocs init writes it for Vercel, Netlify, Cloudflare or GitHub Pages (as a Worker answering with Workers AI, no API key): see Deploying.
Starlight. npm i ondocs ai @ai-sdk/openai, then:
// 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()] })],
});
After astro build, it indexes the pages into dist/ask-index.json, writes llms.txt and the .md pages, and adds an "Ask AI" button with ⌘I. Static site? npx ondocs init. SSR adapter? Nothing to do.
Docusaurus. npm i ondocs ai @ai-sdk/openai @radix-ui/react-dialog cmdk, then:
// docusaurus.config.ts
export default { plugins: ['ondocs/docusaurus'] };
It does the same after docusaurus build, into build/.
Next.js. With OPENAI_API_KEY set, index your content with npx ondocs index ./content --base-url /docs --llms-txt public, then:
// app/api/ask/route.ts
import { openai } from '@ai-sdk/openai';
import { createAskHandler } from 'ondocs/server';
import index from '../../../ask-index.json';
export const POST = createAskHandler({
index,
model: openai('gpt-5.4-mini'),
embeddingModel: openai.embedding('text-embedding-3-small'),
});
and render the dialog in your layout, with its two stylesheets:
// app/layout.tsx
import { AskDialog } from 'ondocs/react';
import 'ondocs/react/styles.css';
import 'ondocs/embed/launcher.css';
// …then <AskDialog launcher /> in the body
Any other site. Index the HTML it builds, write the endpoint with npx ondocs init, and add the script tag:
npx ondocs index public -o public/ask-index.json # embeds with OPENAI_API_KEY, best for the Ask box; -e none for keyword-only
npx ondocs init --out public # plain HTML needs --out; Hugo, Jekyll, MkDocs and Eleventy are detected
# For the Workers AI Worker (init --host github-pages), index with -e workers-ai:@cf/baai/bge-small-en-v1.5
# and CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN set, or -e none: it can't embed questions for an OpenAI index
On a GitHub Pages project site, at https://user.github.io/repo, add --base-url /repo to the index command.
<script src="https://cdn.jsdelivr.net/npm/ondocs@0.18/dist/embed.global.js" defer></script>
Try it without a key. npx ondocs index ./docs -e mock, then npx ondocs dev, serves the ask endpoint and MCP server on localhost, with a mock model that quotes your docs. See Try it locally.
For agents
The same index, served to agents with createMcpHandler:
// app/api/mcp/route.ts
import { createMcpHandler } from 'ondocs/server';
import index from '../../../ask-index.json';
const handler = createMcpHandler({ index, siteName: 'the Acme docs' });
export { handler as POST, handler as GET, handler as DELETE, handler as OPTIONS };
claude mcp add --transport http acme-docs https://docs.acme.dev/api/mcp # Claude Code
codex mcp add acme-docs --url https://docs.acme.dev/api/mcp # Codex
gemini mcp add --transport http --scope user acme-docs https://docs.acme.dev/api/mcp # Gemini CLI
- Protocol. MCP 2026-07-28, and 2025-11-25 back to 2024-11-05 for clients that start with
initialize, tested with the official TypeScript client. - Tools.
searchreturns ranked sections with a snippet and an anchor URL, andfetcha page or section as Markdown, as ChatGPT's connectors expect. - Quality. On docusaurus.io's docs, keyword search puts the right page in the top three for 22 of 22 agent-style queries we wrote in the docs' terms, and 20 of 22 asked as a person asks: a best case, checked in CI (the queries). A reader's own words find it less often (real Stack Overflow questions).
- On your docs. With the plugins'
mcpoption, a page can show an "Add to Cursor / VS Code / Claude" block. - llms.txt. The plugins write it by default, and the CLI with
--llms-txt <dir>.
See MCP server and llms.txt and Markdown pages.
Cost and safety defaults
- A question costs one embedding call and one model call, with at most 8,000 characters of sources in and 800 tokens out, and a follow-up one more short call to rewrite it. Most questions your docs don't cover stop before the model; one that shares enough words with your pages, such as a general programming question, can still reach it.
- An agent's search costs no model call, or one embedding call with an
embeddingModel. - Rate limits are on by default: 10 questions and 60 tool calls a minute per client IP, per server instance. Name your platform's client IP header outside Vercel.
budgetcaps questions and model tokens per UTC day for the whole endpoint,answerCacheanswers repeated questions without a model call, andchallengeadds an optional Turnstile bot check.- Requests must be JSON and bodies are capped; model errors are masked; answers render as text, never HTML, and by default link only to their sources.
- Set a spend limit with your model provider. It is the only hard cap. See Rate limits and security.
How it compares
- Kapa.ai and Inkeep are hosted, take more sources than your docs (forums, issues, chat) and have analytics dashboards; several hosted assistants now serve an MCP endpoint for agents as well. ondocs has
ondocs eval, readers' ratings and a log of unanswered questions to wire yourself. - Algolia DocSearch Ask AI adds answers to DocSearch's search box, with your own LLM provider and key, from the index Algolia's crawler builds on its platform, under an Algolia account. Choose it if you already use DocSearch.
- Context7, DeepWiki and DocSearch MCP serve many projects' docs to agents from one server; if one indexes yours, keep it. Your own endpoint is the first-party copy: your docs as last deployed, at your site's URLs, and
onToolCallshows what agents search for. - Fumadocs has first-party AI chat and an MCP route, native to its framework.
- docusaurus-plugin-mcp-server builds a similar index for an MCP endpoint, more widely used today, with no Ask box.
- The llms.txt plugins (docusaurus-plugin-llms, starlight-llms-txt, vitepress-plugin-llms and others) have more output options. ondocs writes the basics, and steps aside when one is installed.
What ondocs adds: open source you host. The index is a file in your build, the endpoint a function on your host, the model key yours, with no vendor account. See Limits and trade-offs for where it is the wrong tool.
Links
- Getting started, Deploying, API, CLI, Benchmarks and FAQ
- Changelog, Contributing, Security
Requires Node.js 22.13 or later and AI SDK 6 (ai@^6.0.16) or 7 (ai@^7.0.95); see Compatibility. MIT © Diogo Esteves
ondocs MCP questions
How do I add ondocs MCP to Claude Code?
Run claude mcp add ondocs -- npx -y docusaurus-plugin-ondocs in your terminal. Add --scope user to make it available in every project.
How do I add ondocs MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does the MCP server provide?
The server provides search, fetch, and list_pages tools over your documentation index.
Does ondocs require a vector database?
No, it uses a single static index built from your site without needing a vendor or a vector database.