Click on "Install 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., "@mcp-knowledge-server search the knowledge base for 'climate change impacts'"
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.
Production-grade Retrieval-Augmented Generation (RAG) server with centralized knowledge base backed by Qdrant. Exposes identical functionality through Model Context Protocol (MCP) and FastAPI REST API.
Designed for enterprise scale: clean architecture, SOLID principles, dependency injection, and fully env-configurable providers.
Cursor IDE (MCP Client)
↓
MCP Server (stdio / streamable-HTTP)
↓
Application Services
↓
RAG Pipeline → Embedding → Qdrant
↓
PostgreSQL (metadata) + Knowledge BaseLayer | Responsibility |
| FastAPI REST endpoints |
| MCP tool registration (12 tools) |
| Use case orchestration |
| Retrieval pipeline, prompts, compression |
| Entities, ports, exceptions |
| LLM, embeddings, Qdrant, persistence |
| Loaders, chunkers, cleaning |
Related MCP server: vector-mcp
Python 3.12+
uv package manager
Qdrant (local or Docker)
Ollama (optional, for local LLM)
# Clone and setup
git clone <repo-url> mcp-knowledge-server
cd mcp-knowledge-server
cp .env.example .env
# Install dependencies
./scripts/setup.sh
# Start Qdrant (Docker)
docker run -p 6333:6333 qdrant/qdrant:v1.12.5
# Start REST API
uv run mcp-knowledge-server-api
# Start MCP server (stdio for Cursor)
uv run mcp-knowledge-server-mcp-stdiocp .env.example .env
docker compose -f docker/docker-compose.yml upServices:
MCP HTTP: http://localhost:8001/mcp
Qdrant: http://localhost:6333
PostgreSQL: localhost:5432
All settings via .env — never modify source code to change providers.
# Local (macOS)
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:8b
# Cloud
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1Supported LLM providers: openai, anthropic, gemini, groq, together, openrouter, ollama, lmstudio, llamacpp, openai_compatible
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=all-MiniLM-L6-v2Supported: sentence_transformers, openai, ollama, voyage, cohere
CHUNK_STRATEGY=recursive # recursive | token | markdown | semantic
CHUNK_SIZE=1000
CHUNK_OVERLAP=200# Install Ollama
brew install ollama
# Start Ollama
ollama serve
# Pull recommended models
ollama pull qwen3:8b
ollama pull nomic-embed-text
# Configure .env
LLM_PROVIDER=ollama
OLLAMA_MODEL=qwen3:8b
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-textRecommended models: qwen3, qwen2.5, llama3.2, mistral, gemma3, deepseek, phi
Copy .cursor/mcp.json.example to your Cursor MCP settings:
{
"mcpServers": {
"knowledge-server": {
"command": "uv",
"args": ["run", "python", "-m", "app.mcp.main"],
"cwd": "/path/to/mcp-knowledge-server",
"env": {
"LLM_PROVIDER": "ollama",
"OLLAMA_BASE_URL": "http://localhost:11434",
"OLLAMA_MODEL": "qwen3:8b"
}
}
}
}Tool | Description |
| Semantic search over knowledge base |
| Generate RAG answer with citations |
| Ingest a document file |
| Re-ingest an existing document |
| Remove document and vectors |
| List indexed documents |
| Get document metadata |
| Find similar chunks |
| Create a new collection |
| Delete a collection |
| List all collections |
| Server health status |
OpenAPI docs: http://localhost:8000/docs
# Health check
curl http://localhost:8000/health
# Upload document
curl -X POST http://localhost:8000/documents/upload \
-F "file=@documents/sample.txt" \
-F "collection=knowledge_base"
# Search
curl -X POST http://localhost:8000/search \
-H "Content-Type: application/json" \
-d '{"query": "What is this about?", "top_k": 5}'
# RAG answer
curl -X POST http://localhost:8000/rag \
-H "Content-Type: application/json" \
-d '{"query": "Summarize the knowledge base"}'
# List collections
curl http://localhost:8000/collections
# Create collection
curl -X POST http://localhost:8000/collections \
-H "Content-Type: application/json" \
-d '{"name": "my_docs", "description": "My documents"}'PDF, DOCX, TXT, Markdown, HTML, CSV
If OpenAI-compatible: add config to OpenAICompatibleLLMProvider.from_settings() in app/infrastructure/llm/openai_compatible.py
If custom API: implement BaseLLMProvider in app/infrastructure/llm/
Register in LLMProviderFactory in app/infrastructure/llm/factory.py
Add env vars to .env.example
Implement BaseDocumentLoader in app/ingestion/loaders/
Register in LoaderRegistry in app/ingestion/loaders/registry.py
Implement BaseEmbeddingProvider in app/infrastructure/embeddings/
Register in EmbeddingProviderFactory
# Install with dev dependencies
uv sync --all-extras
# Lint
uv run ruff check app tests
uv run black --check app tests
# Type check
uv run mypy app
# Tests
uv run pytest
# Pre-commit
uv run pre-commit install
uv run pre-commit run --all-filesapp/
├── api/ # FastAPI REST API
├── mcp/ # MCP server tools
├── services/ # Application use cases
├── rag/ # RAG pipeline stages
├── domain/ # Entities, ports, exceptions
├── infrastructure/# External adapters
├── ingestion/ # Loaders, chunkers, cleaning
├── config/ # Pydantic settings
├── logging/ # Structured logging
└── container.py # Composition root (DI)
tests/
docker/
scripts/
alembic/Set APP_ENV=production
Use PostgreSQL: DATABASE_URL=postgresql+asyncpg://...
Configure Qdrant with API key and HTTPS
Enable auth: ENABLE_AUTH=true, set API_KEY
Use cloud LLM or dedicated Ollama instance
Run behind reverse proxy (nginx/traefik)
Set resource limits in Docker Compose
See .env.example for the complete list.
MIT
Add a document to the knowledge base.
Args:
file_path: Absolute path to the document file.
collection: Target collection name.
author: Optional document author.
tags: Comma-separated tags.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| author | No | ||
| file_path | Yes | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden of behavioral disclosure. It only says 'Add a document' without detailing side effects, error conditions, permissions, or whether duplicates are checked. For a mutation tool, this is a significant gap.
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 highly concise, with a clear purpose statement followed by a compact Args list. No redundant information is present.
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?
While the description covers the basic purpose and parameters, it lacks usage context and behavioral details. With an output schema present, return values are covered, but the description does not address when to use this tool or its side effects, leaving it minimally viable but incomplete.
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 description adds meaningful semantics beyond the schema: 'Absolute path' clarifies file_path, 'Target collection name' clarifies collection, and 'Comma-separated tags' clarifies tags. However, it omits that collection is optional (default null) and does not specify allowed file types.
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 'Add a document to the knowledge base' with a specific verb and resource. This distinguishes it from sibling tools like update_document, delete_document, and get_document.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites such as existing collections, nor does it explain scenarios where update_document might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new document collection.
Args:
name: Collection name (alphanumeric, hyphens, underscores).
description: Optional collection description.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as error behavior on duplicate names, required permissions, reversibility, or side effects. It only mentions the creation action and parameter names.
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 concise with a single-line purpose followed by a structured Args block. It is front-loaded with the most important information and contains 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?
For a simple create operation with an output schema, the description adequately covers the purpose and both parameters. However, it lacks behavioral details like duplicate handling or prerequisites, which prevents a perfect score.
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 description adds meaningful constraints beyond the schema by specifying that 'name' must be alphanumeric with hyphens and underscores, and clarifies that 'description' is optional. Since schema description coverage is 0%, this compensation is valuable.
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 'Create a new document collection' with a specific verb and resource, distinguishing it from siblings such as add_document, delete_collection, and list_collections.
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 no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It merely states the action without placing it in the broader workflow of collection management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a collection and all its vectors.
Args:
name: Collection name to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 a key behavioral trait: deleting the collection also deletes all its vectors (cascading destructive behavior). It does not mention irreversibility or permissions, but the explicit 'all its vectors' is a meaningful disclosure beyond the basic delete action.
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 concise with the primary action front-loaded and a clear parameter explanation. The 'Args' line is slightly redundant given the schema but efficiently captures the param semantics. No unnecessary 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?
For a single-parameter destructive operation with an output schema present, the description covers the action and the parameter adequately. It could optionally mention error conditions (e.g., if collection doesn't exist), but that's not required for basic completeness. The major side effect (deleting all vectors) is explicitly disclosed.
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 schema has 0% description coverage for the 'name' parameter, but the description compensates with an 'Args' section stating 'name: Collection name to delete.' This adds clear semantic meaning to the parameter, fulfilling the need beyond the schema.
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 opens with 'Delete a collection and all its vectors,' which clearly states the action (delete) and the resource (collection) with a specific scope (all vectors). This distinguishes it from sibling tools like delete_document, which targets individual documents, and create_collection/list_collections, which handle collection lifecycle.
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 implies usage: it's for deleting a collection. However, it does not explicitly state when to use this tool versus delete_document or when not to use it. The guidance is implied by the name and context rather than stated, so it meets the minimum but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document from the knowledge base.
Args:
document_id: UUID of the document to delete.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits itself. It states the action ('Delete') but fails to mention the permanence of the operation, any authorization requirements, or potential side effects on related data. This is insufficient for a destructive tool.
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 concise and front-loaded with the main action. The Args section is neatly formatted and adds value without unnecessary words. It is slightly terse but appropriately sized for the tool's simplicity.
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?
Despite having an output schema, the description omits critical context for a destructive operation: it does not warn that deletion is irreversible, mention error scenarios (e.g., nonexistent document), or note any cascading effects on knowledge base indexes or related data. This is a significant 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?
The input schema only provides a type 'string' with no description. The tool description compensates by specifying that document_id is a 'UUID of the document to delete', adding semantic meaning and fully covering the single parameter.
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 uses the specific verb 'Delete' and identifies the resource as 'a document from the knowledge base', clearly distinguishing it from sibling tools like add_document, update_document, and get_document.
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 implies its purpose through the verb 'Delete' but offers no explicit guidance on when to use it over alternatives, no prerequisites, and no exclusions. It is adequate but relies on the tool's name and obvious intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a document by ID.
Args:
document_id: UUID of the document.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey safety and behavior. It only states 'Get' without explicitly declaring it as read-only or explaining error handling. Minimal disclosure, but sufficient for a simple retrieval.
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?
Two sentences, front-loaded with the core action. No redundant 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?
For a single-parameter retrieval tool with an output schema, the description covers the essential purpose and parameter. It lacks error-case behavior but is otherwise complete given the tool's simplicity.
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 description provides a brief explanation of document_id as a UUID, adding value over the schema's bare string type. It clarifies the expected format.
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 'Get a document by ID', specifying the verb, resource, and selection method. It distinguishes from sibling tools like list_documents and search_documents by indicating it fetches a single document.
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 implies usage when a specific document ID is known, but provides no explicit comparison with alternatives like search_documents or list_documents. There is no 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the health status of the knowledge server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the action is a 'check,' implying a read-only, non-destructive operation, but it does not disclose details about the response format or potential error conditions. This is acceptable for a trivial health-check tool.
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 a single clear sentence with no redundancy or irrelevant information.
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?
The tool is very simple with no parameters, and an output schema exists, so the description adequately covers the tool's scope. No additional context is necessary for this health-check operation.
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 accepts zero parameters, so the input schema is fully complete. The description adds no parameter details because none are needed; baseline 4 applies.
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 identifies the tool's function: checking the health status of the knowledge server. It uses a specific verb ('check') and resource ('health status'), and is distinct from the sibling document/collection management tools.
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?
No explicit guidance on when to use versus alternatives is provided, but the tool's purpose is self-evident and there are no sibling tools with similar health-check functionality. The usage is implied by the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all document collections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and relies on the verb 'list' to imply a read-only operation. Since no annotations are provided, the description does not disclose additional behavioral traits such as pagination, ordering, or potential limitations. However, for a straightforward list operation, this may be sufficient, so a neutral score is appropriate.
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 a single concise sentence with no redundancy. It is front-loaded with the action and resource, making it easy to parse.
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?
For a simple list operation with an output schema defined, the description covers the essential purpose and scope. The tool's context is clear from its name and sibling tools, so no additional information is needed.
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 zero parameters, and the schema is complete. The description correctly implies that no arguments are needed, and the baseline for parameterless tools is 4. No additional parameter information is required.
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 uses the specific verb 'list' and identifies the resource as 'document collections', clearly distinguishing it from sibling tools like list_documents and create_collection. It is unambiguous and directly states the tool's function.
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?
No guidance is provided on when to use this tool versus alternatives. The description simply states the action without any context, prerequisites, or exclusions, leaving the agent without information about when this tool is preferable to others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List documents in the knowledge base.
Args:
collection: Optional collection filter.
limit: Maximum number of documents to return.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the action and parameters, omitting details like read-only nature, default pagination behavior, or whether it returns full documents or metadata. Nothing about side effects or prerequisites is mentioned.
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 concise, with two short lines and an Args section. No fluff or repetition. It is front-loaded with the action, and the parameter explanations are efficient, although not exhaustive.
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?
The tool is simple with two optional parameters and an output schema, so the description covers the essentials: purpose and parameter meaning. However, it lacks usage context and any mention of return format or limitations, making it only minimally complete for an agent to fully understand and invoke the tool correctly.
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 schema has zero description coverage (0%), so the description is the only source of parameter meaning. It adds 'Optional' to collection and 'Maximum' to limit, which is helpful but minimal. It fails to clarify what a collection is or provide examples, so it only partially compensates for the schema gap.
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 lists documents in the knowledge base, with a specific verb and resource. It is distinct from siblings like get_document (single document) and list_collections (collections), though it does not explicitly mention alternatives or edge cases.
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 no guidance on when to use this tool versus alternatives like search_documents or similar_documents. No context is given for selection or exclusions, leaving the agent to infer based solely on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a RAG answer with citations from the knowledge base.
Args:
query: The question to answer.
collection: Optional collection to search in.
top_k: Number of context chunks to retrieve.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description bears the full burden of behavioral disclosure. It explains that the tool generates an answer and retrieves context chunks, but it does not state whether the operation is read-only, requires special permissions, or has any side effects.
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 a single focused sentence followed by a structured Args list. There is no redundant information, and each line adds value without inflating length.
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?
For a simple tool with three parameters and an existing output schema, the description covers the core purpose and parameter semantics. It could be improved by mentioning when to use this tool instead of sibling search tools, but overall it is contextually adequate.
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 description explicitly documents all three parameters (query, collection, top_k) with concise, meaningful descriptions that go beyond the schema's type-only definitions. Since schema description coverage is 0%, this fully compensates and adds clear semantics.
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 uses the specific verb 'Generate' and identifies the resource as 'a RAG answer with citations from the knowledge base'. This clearly distinguishes it from sibling tools like search_documents, which ostensibly retrieve raw documents rather than generating answers.
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 states what the tool does but does not specify when to use it over sibling tools such as search_documents or similar_documents. No exclusions or alternative tools are mentioned, so usage guidance is only implied by the RAG-specific wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search documents by semantic similarity.
Args:
query: The search query text.
collection: Optional collection name to search in.
top_k: Number of results to return (default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that results are based on semantic similarity, but does not state whether the operation is read-only, any side effects, or error conditions. The search verb implies a non-mutating action, but this is not explicit.
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 a concise docstring with a clear opening sentence and a compact arg list. It contains no unnecessary words and is well-structured for quick parsing.
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?
The tool is simple, but its relationship to similar_documents is unaddressed. The description also does not mention whether a collection must exist or how results are ordered. The output schema exists, so return details are covered elsewhere, but behavioral prerequisites are missing.
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 description provides brief semantics for all three parameters: query text, optional collection name, and number of results, including the default for top_k. Since the schema has no descriptions (0% coverage), this adds meaningful value beyond the property names.
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 'Search documents by semantic similarity', which identifies the verb (search), resource (documents), and method (semantic similarity). This is specific enough to distinguish from listing or retrieving documents, though similar_documents may overlap.
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?
No explicit guidance is provided on when to use this tool versus similar_documents or list_documents. While semantic similarity implies query-based search, there is no mention of alternatives, exclusions, or specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find documents similar to a given chunk.
Args:
chunk_id: The chunk ID to find similar documents for.
collection: Optional collection to search in.
top_k: Number of similar results to return.
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | ||
| chunk_id | Yes | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like read-only nature, side effects, or authentication needs. It only lists parameters, which duplicates the schema, and does not explain behavior such as ordering or failure modes.
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 concise and front-loaded with a clear purpose, followed by a neatly formatted Args section. Every sentence earns its place with no 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?
The output schema exists, so return format is handled. The description covers the core functionality and all parameters adequately for a relatively simple tool, though it does not explain the notion of similarity or any edge 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?
Despite zero schema description coverage, the description adds meaning to each parameter: 'Optional collection to search in' clarifies that collection is optional, and 'Number of similar results to return' explains top_k. This goes beyond mere parameter names, though it briefly stays close to self-evident definitions.
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 'Find documents similar to a given chunk', which uses a specific verb and resource. It distinguishes itself from sibling tools like 'search_documents' by emphasizing similarity to a chunk rather than a query.
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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or preferred scenarios, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing document by re-ingesting it.
Args:
document_id: UUID of the document to update.
file_path: Absolute path to the new document file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions 're-ingesting' as the mechanism but does not disclose side effects, requirements, or whether the operation is destructive. There is no mention of permission needs, potential data loss, or response behavior.
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 concise and front-loaded with the primary action, followed by a structured argument list. Every sentence earns its place without fluff.
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?
For a two-parameter tool with an output schema, this is minimally adequate. It explains the basic purpose and parameter meanings, but lacks usage guidance and behavioral disclosures (e.g., does updating replace the entire document, are there prerequisites?). It does not cover edge cases or error scenarios.
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. The Args section clearly explains both parameters: document_id as 'UUID of the document to update' and file_path as 'Absolute path to the new document file,' adding meaningful context beyond the bare schema.
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 states a specific verb+resource: 'Update an existing document by re-ingesting it.' This clearly distinguishes it from siblings like add_document, delete_document, and get_document.
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?
No explicit guidance on when to use this tool versus alternatives. The phrase 'existing document' implies it is not for new documents, but no alternatives are mentioned and no exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add_documentcreate_collectiondelete_collectiondelete_documentget_documenthealth_checklist_collectionslist_documentsrag_answersearch_documentssimilar_documentsupdate_documentEach tool targets a distinct action on either documents or collections. search_documents and similar_documents are differentiated by input (query text vs. chunk ID), and rag_answer is clearly for answer generation, so there is no ambiguity.
Most tools follow a verb_noun pattern with snake_case (add_document, delete_document, list_collections). However, 'add' and 'create' are used interchangeably for creation, and 'similar_documents' uses an adjective instead of a verb, creating minor inconsistencies.
With 12 tools, the server covers document CRUD, collection management, search/retrieval, and health monitoring. This is well-scoped for a knowledge server and each tool earns its place without redundancy.
The tool surface provides full document lifecycle (add, get, update, delete, list), collection management (create, delete, list), semantic search, similar-document lookup, and RAG. Minor gaps such as missing get_collection or update_collection exist, but core workflows are fully covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NavinAnik/mcp-knowledge-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
