NookDocs ships a per-project Model Context Protocol endpoint at https://{slug}.nookdocs.site/mcp. AI clients connect once, then your docs become first-class context for every chat — agents can search, fetch full pages, and look up API operations without leaving their editor.
Tools exposed
Tool names carry your project's name, so a reader connected to several docs
servers can tell which site each tool reaches. A project called Acme Docs
exposes search_acme_docs, get_acme_docs_page, and so on — the shapes below
use {project} for that part.
| Tool | Description |
search_{project}(query, limit?, version?) | Full-text search across all pages. Each hit is the best-matching section of a page: title, the section heading, an absolute anchored URL ready to cite, and a bounded excerpt. |
get_{project}_page(path, section?, lines?, version?, raw?, paths?) | Returns a page, led by its absolute URL and last-updated date. section: "Props" returns one heading and its content with an anchored URL; lines: "40-80" returns a range numbered to match rg output; raw: true returns the synced file with <Visibility> blocks intact — use it when editing; paths: [...] reads up to 5 full pages in one call. |
list_{project}_pages(prefix?, limit?, version?) | Lists pages, optionally filtered by a path prefix (e.g. /api/). |
search_{project}_openapi(query) | Searches OpenAPI operations by operationId, summary, path, or method. |
query_{project}_docs(command) | Literal search and structure: rg [-l] [-i] [-C n] "pattern" [/prefix] and tree [-L n]. Linear-time RE2 patterns, like real ripgrep — no lookahead or backreferences. Not a shell — two commands, no pipes. |
validate_{project}_mdx(source, path?) | Checks a page before it's committed: syntax that won't compile, and components this site doesn't have. |
validate_{project}_config(config) | Validates a config before it's committed. Reports errors and silently-ignored keys. |
submit_{project}_feedback(path, feedback) | Reports a documentation gap to your backlog. The only tool that writes; capped at 10 reports per site per hour. |
The three read tools take an optional version. Without it they answer from
your current version; pass "v2" and they answer from that one. It matters on
a site with more than one version, where an agent that searched one version and
then read a page from another gets a confidently wrong answer.
Checking a page before you commit it
There is no local build to run against a NookDocs site, so until a page is pushed and synced, nothing tells you it's wrong. Two tools close that gap, and they catch different failures.
validate_{project}_mdx parses the file with the same parser the site renders
with. Syntax it can't compile means readers get an error box where the page
should be. But the failure worth the tool is the quiet one: a component this
site doesn't have renders as nothing at all — no error, no placeholder, not
even the text inside it. The rest of the page is fine, so it looks finished and
is silently missing a section. Component names carried over from another docs
platform are the usual cause, and the check names the closest real one.
validate_{project}_config runs the config validator, separating errors that
stop the config loading from keys that are ignored silently.
The MDX check also verifies what the server can verify from its own data:
internal links resolve against the site's real page list (a link to a missing
page warns — it's a 404 unless that page ships in the same push), and icon
names resolve against the icon set the renderer uses (an unknown name renders
as literal text, not a glyph). Neither check reads intent: a page listed in
navigation that you haven't written yet still validates.
The name comes from your project, not the URL, so it stays the same whether the
site is served from a nookdocs.site subdomain, a custom domain, or a subpath.
The authoring guide
Alongside the tools, the server exposes one resource — a short guide to building a site with NookDocs: where files go, what frontmatter a page needs, how navigation is wired, which components exist, how an API reference is set up.
An assistant that connects reads it once and can start writing pages. That is
a different question from what the tools answer: searching the docs tells it
what NookDocs does, not where to put the file it is about to create. The
alternative — reading /llms-full.txt — is roughly 250,000 tokens and leaves
no room to work in.
| URI | nookdocs://guide/authoring |
| Size | ~3,800 tokens |
| Read via | resources/read |
Assistants that support MCP resources surface it automatically; nothing to configure.
The config reference
A second resource, nookdocs://reference/config, lists every key
nookdocs.config.json accepts — over 300 once nesting, array entries and the
navigation types are counted — with its type, allowed values, defaults,
required fields and format constraints.
The authoring guide names the top-level keys and stops, which is the right size for something read on connect. This is the reference to consult while editing config. It matters because an unknown key is ignored silently: without the list, a typo and a feature that doesn't work look identical.
Generated from the same schema the config validates against, so it can't drift from what the platform accepts.
Agent feedback
An agent that reads a page and still can't do the thing is the best detector of a missing paragraph you have — and the only reader who will reliably say so. Human feedback is a thumbs-down with no comment; an agent can name the page it read and what wasn't in it.
submit_{project}_feedback writes to the same backlog as the page widget,
tagged source: mcp so you can read the two separately. Filter by it in
Feedback — mixed together, agent volume buries the human signal.
Three limits, because this is the only tool that writes:
10 reports per site per hour. A retry loop can file faster than anyone can triage.
The path must resolve to a real, visible page. An agent sends whatever it inferred; private pages are rejected like missing ones.
No GitHub issue is ever opened from MCP. The widget can, because a browser reader is a person. This endpoint is unauthenticated, and writing to your repo on an anonymous agent's say-so isn't a trade worth making.
Private pages
Pages marked private: true are excluded from every tool: get_page answers
as it would for a page that doesn't exist, and they appear in neither search
results nor listings. The site's access control governs MCP the same way it
governs a browser. This extends to the API reference: an OpenAPI operation
whose only page is private is excluded from search_{project}_openapi too.
Endpoint
https://{your-project-slug}.nookdocs.site/mcpIf you have a verified custom domain configured, that works too:
https://docs.example.com/mcpA GET to the URL returns a small JSON discovery payload — handy for verifying the connection in a browser before wiring up a client.
Transport: JSON-RPC 2.0 over HTTP POST, verified against Claude Desktop's
custom connectors and the OpenAI Agents SDK's MCPServerStreamableHttp
client — both connect, list tools and call them. The optional Streamable-HTTP
session extras (SSE GET stream, Mcp-Session-Id) are not implemented;
clients degrade to plain POST, which every verified client does.
Connecting Claude
Anthropic's Claude desktop app (macOS, Windows, Linux) supports MCP natively. Add an entry under mcpServers in the platform-appropriate config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"your-project-docs": {
"url": "https://your-project.nookdocs.site/mcp"
}
}
}Restart Claude. The four tools above will appear in the MCP tool picker on every conversation.
Claude.ai (the web app) doesn't ship MCP support yet — use the desktop app or the Claude Code CLI for now.
Connecting Cursor
Drop the same mcpServers map into either .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"your-project-docs": {
"url": "https://your-project.nookdocs.site/mcp"
}
}
}Connecting Continue
Add to ~/.continue/config.json:
{
"mcpServers": {
"your-project-docs": {
"url": "https://your-project.nookdocs.site/mcp"
}
}
}Connecting Cline
Open VS Code → Cline panel → MCP Servers → settings.json:
{
"mcpServers": {
"your-project-docs": {
"url": "https://your-project.nookdocs.site/mcp"
}
}
}Plan availability
| Plan | MCP server |
| Free | ✅ |
| Pro | ✅ |
| Team | ✅ |
| Enterprise | ✅ |
MCP is on for every tier — agent-readable docs are a primitive, not a paywalled extra. The endpoint serves the pages your site publishes; anything marked private: true is excluded from every tool.
Why it matters
Agents that can read your docs directly write better code against your API and stop hallucinating endpoints that don't exist. That's why it isn't gated: your OSS users get the same agent experience your paying customers do.
The endpoint is public — anyone with the URL can call it. Every tool reads, except the feedback tool, which records a note for your backlog and changes no page. Authenticated MCP, for sites whose docs are private end to end, is on the roadmap.
Settings → MCP
Open any project, head to Settings → MCP to copy the URL and ready-made config snippets for the four most common clients. The page also has a Test endpoint button that opens the discovery payload in a new tab.