Internal Documentation Search
Exposes an internal knowledge base composed of Markdown documents to AI assistants, enabling full-text search, category and tag-based filtering, and retrieval of content such as standards, runbooks, and architecture decision records (ADRs).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Internal Documentation Searchfind the runbook for handling high database latency"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Internal Documentation Search — MCP Server
What's in the box: An MCP server with 5 tools, 3 prompt templates, and 2 resources backed by a knowledge base of 16 markdown documents (standards, runbooks, ADRs). Includes RBAC with 3 roles, sliding-window rate limiting, input sanitisation, and a CLI scraper to ingest docs from URLs. RAG (ChromaDB) is available as an optional extra — keyword search works well for structured docs with clear titles and tags, but RAG adds value when engineers phrase queries differently from how documents are written (e.g. searching "why do we use Kafka" against an ADR titled "Adopt Event-Driven Architecture").
An MCP server that exposes an internal knowledge base to AI assistants, enabling engineers to search standards, runbooks, and architecture decisions from within their coding workflow.
Why this scenario? Finding internal docs is one of the highest-friction points for engineers. This brings company-specific knowledge directly into the AI assistant, keeping engineers in flow.
Architecture
AI Assistant ◄──MCP (stdio)──► MCP Server
├─ config.py (Pydantic BaseSettings)
├─ auth.py (RBAC + rate limiting)
├─ models.py (Document, Category, enums)
├─ server.py (tools, prompts, resources)
├─ scraper.py (CLI: scrape URLs → markdown)
└─ kb/ (knowledge base sub-package)
├─ store.py (document store + search)
├─ loader.py (markdown file loader)
└─ rag.py (ChromaDB vector search)Documents are stored as markdown files with YAML frontmatter in docs/knowledge_base/ (16 docs: 6 Standards, 5 Runbooks, 5 ADRs). They are loaded at startup by the document loader.
Tools
Tool | Purpose |
| Free-text search with optional category/tag filters, ranked by relevance |
| Full document content by ID, with semantically related docs |
| Available categories |
| All tags for refining searches |
| Browse all documents, optionally by category |
Prompts
Prompt | Purpose |
| Structured incident investigation using runbooks |
| Review code against internal standards |
| Explain why a technology was adopted (ADRs) |
Resources
docs://categories— list of categoriesdocs://document/{doc_id}— individual document access
RAG (optional)
When enabled, search uses hybrid ranking — keyword scoring blended with ChromaDB vector similarity. Related documents in get_document are found via semantic similarity instead of hardcoded lists.
# Install with RAG support
uv pip install -e '.[rag]'
# Run with RAG enabled
RAG_ENABLED=true uv run internal-docs-mcpScraping new documents
Scrape any URL into a knowledge base markdown file:
uv pip install -e '.[scrape]'
internal-docs-scrape https://example.com/some-doc \
--id EXT-001 \
--title "External Integration Guide" \
--category standard \
--tags integration,apiFiles are saved to docs/knowledge_base/ and loaded automatically on next server start.
Setup
Prerequisites: Python 3.12+, uv (recommended) or pip
# Install (core)
uv pip install -e '.[dev]'
# Install all extras (RAG + scraping)
uv pip install -e '.[all]'
# Run
python -m internal_docs_mcp
# Test
uv run pytest tests/ -v
# Lint
uv run ruff check src/ tests/Connect to Claude Code
claude mcp add internal-docs /path/to/internal-docs-mcp/run_server.shWhat I Would Improve
Note: This project uses local markdown files as the data source to keep the demo self-contained. In a real production setup the MCP server would connect to live APIs and databases — e.g. Confluence/GitLab wikis, PostgreSQL, Elasticsearch — so engineers always get up-to-date results without manual file management.
Real data source — Connect to Confluence/GitLab wikis via API with a Redis cache.
RBAC via SSO — Map caller identity from SSO tokens instead of static API keys.
Prompt injection classifier — Add Lakera Guard or similar instead of relying on character-level sanitisation.
Document freshness — Flag docs not updated in >6 months as potentially stale in search results.
Tag match mode — Add
tag_matchparameter ("any"vs"all") tosearch_internal_docssotags=["kafka","kubernetes"]can return docs matching either tag.Feedback loop — Thumbs-up/down on results to improve ranking.
SSE transport — Centralised server deployment for the whole org.
Audit log to JSONL — Append every tool call + outcome (timestamp, doc IDs, role, injection flags) to a file for compliance and debugging.
Usage analytics tool — Admin-only
get_usage_statstool that tracks popular queries, most-accessed docs, and zero-result searches to surface knowledge gaps.Onboarding prompt —
onboard_engineer(team, role)prompt template that guides new hires to relevant standards + ADRs for their team without knowing what to search for.
Available Tools
5 toolsget_documentA
Retrieve an internal document by its ID.
Use this after search_internal_docs to get details of a specific document. Document IDs follow the format: STD-001, RUN-002, ADR-003, etc.
Args: document_id: The document identifier (e.g., "STD-001", "RUN-002"). summary: When True, return only a summary (first 500 chars) instead of the full content. Useful for long documents to save context.
Returns: JSON string with the document content (or summary), or an error if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| summary | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool retrieves content or summaries and returns JSON or errors, which covers basic behavior. However, it lacks details on permissions, rate limits, or side effects, leaving gaps for a retrieval tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by usage guidance, parameter details, and return info. Each sentence adds value without redundancy, and it's structured with clear sections (Args, Returns) for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an output schema present, the description is mostly complete. It covers purpose, usage, parameters, and returns adequately. However, it could improve by mentioning error handling specifics or output structure details, though the output schema mitigates this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the schema: it explains the document_id format (e.g., 'STD-001'), clarifies the summary parameter's effect (returns first 500 chars when True to save context), and provides examples, making parameters well-understood.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and resource 'internal document by its ID', making the purpose specific. It distinguishes from siblings by focusing on single-document retrieval rather than listing, categorizing, tagging, or searching multiple documents, which is explicitly mentioned in the usage guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this after search_internal_docs to get details of a specific document', providing clear when-to-use guidance. It differentiates from siblings by implying this tool is for detailed retrieval post-search, while others handle listing or broader searches, though it doesn't explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_all_docsA
List all documents in the knowledge base, optionally filtered by category.
Use this to get an overview of everything available. For specific questions, prefer search_internal_docs instead.
Args: category: Optional filter — one of "standard", "runbook", or "adr".
Returns: JSON string with document summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the tool's behavior (listing with optional filtering) and output format (JSON string with document summaries), but lacks details on permissions, rate limits, pagination, or error handling. It adds some context beyond basic functionality but not comprehensive behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, usage guidelines second, and parameter/return details in labeled sections. Every sentence adds value: the first states purpose, the second provides usage context, and the Args/Returns sections clarify inputs/outputs without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 parameter with no schema descriptions and an output schema exists, the description provides good coverage: purpose, usage guidelines, parameter semantics, and return format. It doesn't need to detail return values due to the output schema. Minor gaps include lack of behavioral details like pagination or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the 'category' parameter's purpose ('Optional filter'), provides allowed values ('standard', 'runbook', or 'adr'), and clarifies it's optional. This adds meaningful semantics beyond the schema's basic type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all documents in the knowledge base'), and distinguishes it from siblings by mentioning 'search_internal_docs' as an alternative for specific questions. It specifies the scope ('everything available') and optional filtering capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('to get an overview of everything available') and when not to use ('For specific questions, prefer search_internal_docs instead'). It names the alternative tool, providing clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_doc_categoriesA
List all available documentation categories with descriptions.
Use this to understand what kinds of documents are available in the knowledge base before searching.
Returns: JSON string with available categories and their descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by stating it 'List all available documentation categories with descriptions' and specifies the return format ('JSON string with available categories and their descriptions'), which covers key aspects like output structure. However, it lacks details on potential limitations (e.g., pagination, error cases), keeping it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by usage guidance and return details. Every sentence adds value without redundancy, and the structure is logical and efficient, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, but with an output schema), the description is complete. It explains what the tool does, when to use it, and the return format, which is sufficient for an agent to invoke it correctly. The presence of an output schema means the description doesn't need to detail return values further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100% (as there are no parameters to describe). The description does not add parameter-specific information, which is unnecessary here. A baseline of 4 is appropriate since no parameters exist, and the description compensates by clearly explaining the tool's purpose and output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all available documentation categories with descriptions') and distinguishes it from siblings like 'list_all_docs' (which lists documents) and 'list_doc_tags' (which lists tags). It identifies both the verb ('List') and resource ('documentation categories'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use this to understand what kinds of documents are available in the knowledge base before searching'), providing clear context and distinguishing it from alternatives like 'search_internal_docs' (for searching) and 'list_all_docs' (for listing documents). It effectively guides the agent on the tool's role in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_doc_tagsA
List all available tags used across internal documents.
Use this to discover what topics are covered and to refine searches with tag filters.
Returns: JSON string with all available tags sorted alphabetically.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'all available tags sorted alphabetically' and is used for discovery, but it does not mention behavioral traits like rate limits, authentication needs, or whether it's read-only (though implied by 'List'). The description adds some context but lacks details on performance or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, followed by usage guidelines and return details. Every sentence earns its place: the first states what it does, the second explains why to use it, and the third specifies the output format. It is efficiently structured with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, output schema exists), the description is mostly complete. It explains the purpose, usage, and output format. However, with no annotations, it could benefit from mentioning that it's a read-only operation or any limitations, but the output schema reduces the need for return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description does not add parameter information, which is appropriate. A baseline of 4 is applied as it compensates for the lack of parameters by focusing on usage and output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all available tags used across internal documents.' It specifies the verb ('List'), resource ('tags'), and scope ('used across internal documents'), and distinguishes it from siblings like list_all_docs (which lists documents) or list_doc_categories (which lists categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this to discover what topics are covered and to refine searches with tag filters.' It explains when to use the tool (for discovering topics and refining searches) and implies an alternative (using tag filters in searches, possibly with search_internal_docs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_internal_docsA
Search the internal knowledge base for standards, runbooks, and architecture decisions.
Use this tool when an engineer asks about:
How something should be done (standards)
How to respond to an incident (runbooks)
Why an architectural choice was made (ADRs)
Args: query: Free-text search query describing what the engineer is looking for. category: Optional filter — one of "standard", "runbook", or "adr". tags: Optional list of tags to filter by (e.g. ["python", "security"]).
Returns: JSON string with matching documents (summaries) or a not-found message.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| category | No | ||
| tags | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the search behavior and return format (JSON string with matching documents or not-found message), which is helpful. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, if there are rate limits, authentication requirements, or how results are ranked/limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with the core purpose, provides usage guidelines with bullet points, then documents parameters clearly, and ends with return information. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, search functionality) and the presence of an output schema (which handles return values), the description is quite complete. It covers purpose, usage guidelines, and parameter semantics effectively. The main gap is the lack of behavioral transparency details that would be important for a search tool (like rate limits or result limits).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the lack of schema documentation. It successfully explains all three parameters: query (free-text search), category (optional filter with valid values), and tags (optional list filter with examples). This adds substantial meaning beyond the bare schema, though it doesn't specify exact format requirements for tags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches an internal knowledge base for specific document types (standards, runbooks, architecture decisions). It uses the specific verb 'search' with the resource 'internal knowledge base' and distinguishes itself from siblings by focusing on search functionality rather than retrieval or listing operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool with three concrete examples (engineer asks about how something should be done, incident response, or architectural choices). It distinguishes this search tool from siblings like get_document (likely for retrieving specific documents) and list_all_docs (likely for listing without search).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
get_document - First observed
list_all_docs - First observed
list_doc_categories - First observed
list_doc_tags - First observed
search_internal_docs
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose with no overlap: get_document retrieves a specific document, list_all_docs lists all documents, list_doc_categories lists categories, list_doc_tags lists tags, and search_internal_docs searches documents. The descriptions explicitly differentiate them, such as noting to use search_internal_docs for specific questions instead of list_all_docs.
All tool names follow a consistent verb_noun pattern with snake_case: get_document, list_all_docs, list_doc_categories, list_doc_tags, and search_internal_docs. The verbs (get, list, search) are used appropriately and predictably across the set.
With 5 tools, this server is well-scoped for internal documentation search, covering core operations like retrieval, listing, categorization, tagging, and searching. Each tool earns its place without redundancy or bloat, fitting typical needs for a knowledge base interface.
The tool surface is complete for the domain of internal documentation search, covering all essential CRUD-like operations: listing (list_all_docs, list_doc_categories, list_doc_tags), retrieving (get_document), and searching (search_internal_docs). There are no obvious gaps, and the tools support filtering and summarization for efficient agent workflows.
Related MCP Connectors
- KumbukaOAuthai.kumbuka
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Your company's brain for AI agents. Cited, permission-aware knowledge across every system.
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
