An MCP Server Over Your Own Documentation
Expose your docs as tools any MCP client can use — the read-only first server to build.
The problem
MCP integrations get written badly because people start with something that can cause damage. A read-only server over documentation teaches the part that actually matters — schema design — with no tool that can break anything.
Who uses it: Letting an assistant answer questions about your own product docs without pasting them into a prompt.
Before you start
- Basic Python or TypeScript
- A folder of markdown or HTML docs
Stack
Architecture
- 01A server exposing three narrow tools rather than one general one
- 02search_docs(query, limit) — returns titles, paths and snippets
- 03read_doc(path) — returns one document by exact path
- 04list_sections(path) — returns the headings within a document
- 05No write tools at all in version one
Build it, in order
01Index the docs
Keyword search is enough to start; semantic search is an upgrade, not a prerequisite. Store path, title, headings and body.
02Write the tool schemas first
Before any implementation. The schema is the interface the model programs against, and getting it right is most of the work. State exactly what each tool returns and any limits.
03Implement the three tools
Keep them narrow. One tool taking arbitrary input moves all the safety into the prompt, and prompts are not access control.
04Test with a real client
Connect it and ask questions you know the answers to. Watch which tool the model chooses. Wrong choices are almost always a description problem, not a model problem.
How to know it works
- Fifteen questions with a known correct document
- Measure whether the model chose the right tool and whether it found the right document
- Rewrite descriptions for every wrong tool choice and re-run — this is the loop that teaches schema design
What breaks on real input
- Vague descriptions causing the model to call search when it should read a known path
- Returning entire documents and blowing the context window; return snippets and let it request the full file
- No result limit, so a broad query returns everything
Deployment
- Run locally over stdio first; that is how most clients connect
- Only move to a hosted transport when more than one machine needs it
- Version the tool schemas — changing a description changes behaviour
Repository structure
server/ — MCP server entry point server/tools/ — one file per tool with its schema index/ — the document index builder eval/ — the fifteen questions and which document answers each README.md — how to connect it to a client
A layout to create. There is no repository to clone — building it is the point.
Explaining An MCP Server Over Your Own Documentation in an interview
The interesting answer is why three narrow tools rather than one flexible one. A single query tool taking arbitrary input is easier to write and much harder for a model to use correctly, and it puts every safety decision in the prompt. Narrow tools with tight schemas are more code and fewer wrong calls.
Resume lines
- Built an MCP server exposing documentation search and retrieval as schema-defined tools
- Improved tool-selection accuracy by rewriting tool descriptions against a fixed evaluation set
Take it further
- Add semantic search alongside keyword and compare selection accuracy
- Add a prompts capability offering common questions as templates
- Add a write tool with a confirmation step, and think hard about its blast radius first