Connapse is an open-source knowledge backend for AI agents with container-isolated document management and hybrid search capabilities.
Container Management
Create, list, and delete isolated knowledge containers, each with its own vector index
Get container statistics: document/chunk counts, storage size, embedding model info, and last indexed time
File Operations
Upload single or bulk files (up to 100 at once) via base64-encoded content or raw text; files are automatically parsed, chunked, embedded, and made searchable
Supports PDF, DOCX, PPTX, Markdown, text, and Office formats with configurable chunking strategies (Semantic, FixedSize, Recursive)
List files/folders within a container, retrieve full document text by ID or path, and delete files individually or in bulk
Search & Retrieval
Perform Semantic (vector), Keyword (full-text), or Hybrid searches within containers
Filter by folder path, configure topK results, and set a minimum similarity score threshold
AI Agent Integration
11 MCP tools available for Claude and other MCP clients to query and build knowledge bases programmatically
Configuration & Security
Dynamically switch embedding providers (Ollama, OpenAI, Azure OpenAI) and LLM providers at runtime per container
Enterprise-grade authentication, RBAC, audit logging, rate limiting, and cloud identity linking (AWS IAM Identity Center, Azure AD)
Integrates with S3, Azure Blob, MinIO, or local filesystems
Connects existing MinIO object storage as a document source, enabling the indexing and organization of files into isolated knowledge containers.
Supports local embeddings and LLM processing via Ollama for runtime-configurable document indexing and search.
Integrates with OpenAI to provide embedding and language model services for processing documents and executing hybrid search queries.
Your AI agents forget everything between sessions. Connapse fixes that.
Every time you start a new conversation, your AI agent starts from zero — no memory of past research, no access to your documents, no accumulated knowledge. Connapse is an open-source knowledge backend that gives agents persistent, searchable memory. Upload documents or point it at your existing Amazon S3 buckets, Azure Blob Storage containers, or local filesystems. Agents query and build their own research corpus via 11 MCP tools, REST API, or CLI. Container-isolated, hybrid search (vector + keyword), self-hosted and private. Deploy in 60 seconds with Docker. Built on .NET 10.
AI agents query your knowledge base through the MCP server, receiving structured answers with source citations from your documents.
Switch embedding providers, tune chunking parameters, and configure search — all at runtime, without restarting.
git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001.NET 10 SDK (for development)
(Optional) Ollama for local embeddings
# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse
# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)
# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d
# Open http://localhost:5001 — log in with the admin credentials aboveThe first run will:
Pull Docker images (~2-5 minutes)
Initialize PostgreSQL with pgvector extension and run EF Core migrations
Create MinIO buckets
Seed the admin account (from env vars) and start the web application
# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio
# Run the web app locally
dotnet run --project src/Connapse.Web
# Run all tests
dotnet test
# Run just unit tests
dotnet test --filter "Category=Unit"The connapse CLI is published separately at Destrayon/connapse-cli.
Install:
dotnet tool install -g Connapse.CLI
# or: download a binary from https://github.com/Destrayon/connapse-cli/releases/latestGet started:
connapse auth login --server https://localhost:5001
connapse --helpConnapse includes a Model Context Protocol (MCP) server for integration with Claude and any MCP client.
Setup: Create an agent API key via the web UI (Settings → Agent API Keys), then add the config snippet for your client:
claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"Add to your claude_desktop_config.json:
{
"mcpServers": {
"connapse": {
"transport": "streamable-http",
"url": "http://localhost:5001/mcp",
"headers": {
"X-Agent-Api-Key": "YOUR_API_KEY"
}
}
}
}Add to your .vscode/settings.json (VS Code) or Cursor MCP config:
{
"mcp": {
"servers": {
"connapse": {
"transport": "streamable-http",
"url": "http://localhost:5001/mcp",
"headers": {
"X-Agent-Api-Key": "${input:connapseApiKey}"
}
}
}
}
}VS Code will prompt for the API key on first use.
The MCP server exposes:
Tool | Description |
| Create a new container for organizing files |
| List all containers with document counts |
| Delete a container |
| Get container statistics (documents, chunks, storage, embeddings) |
| Upload a single file to a container |
| Upload up to 100 files in one operation |
| List files and folders at a path |
| Retrieve full parsed text content of a document |
| Delete a single file from a container |
| Delete up to 100 files in one operation |
| Semantic, keyword, or hybrid search within a container |
Full reference: See docs/mcp-tools.md for parameter tables, return formats, error cases, and usage examples.
Containers and sources:
container_listtags each scopemanagedorsource. A source is an external system Connapse mirrors read-only — searchable, but never browsable and never writable.list_filesand every write tool resolve containers only; pass a source id and they report it as not found. See docs/connectors.md.
"Create a container called 'project-research' for my architecture notes"
"Upload all the PDFs in my downloads folder to the project-research container"
"Search my project-research container for information about rate limiting strategies"
"List all files in the /notes/ folder of my project-research container"
"Get the full text of distributed-systems-notes.md from project-research"
"Delete meeting-2026-03-14.md from project-research and upload this updated version"
"Delete all files in the /drafts/ folder of project-research"
"How many documents and chunks are in my project-research container?"
Connection refused on localhost:5001 — Docker not running or port conflict. Check docker compose ps and docker compose logs web.
401 Unauthorized / API key not working — Verify the key in Settings > Agent API Keys. Keys are shown once at creation.
Tools not appearing in Claude — Restart your MCP client after config changes. Verify endpoint with curl http://localhost:5001/mcp.
Uploads failing or timing out — Check file type is in the allowlist. Max file size depends on server config.
Search returns no results — Documents need time to embed after upload. Check container stats for embedding progress.
Related MCP server: mnemostack
🗂️ Container-Isolated Knowledge — Each project gets its own vector index, storage connector, and search configuration. No cross-contamination between projects, teams, or clients.
🔍 Hybrid Search — Vector similarity + keyword full-text with configurable fusion (convex combination, DBSF, AutoCut). Get results that pure vector search misses.
🧠 Multi-Provider AI — Swap between Ollama, OpenAI, Azure OpenAI, and Anthropic for both embeddings and LLM — at runtime, per container, without restarting.
🔌 Index Your Existing Storage — Connect MinIO, local filesystem (live file watching), Amazon S3 (IAM auth), or Azure Blob Storage (managed identity). Your files stay where they are.
🤖 4 Access Surfaces — Web UI, REST API, CLI (native binaries), and MCP server for Claude. Built for humans, scripts, and AI agents equally.
🔐 Enterprise Auth — Multi-tier RBAC (Cookie + OAuth 2.1 + PAT + JWT) with Azure AD identity linking. Per-user filtering of search results by cloud permissions is in progress, not yet enforced.
🐳 One-Command Deploy — Docker Compose with PostgreSQL + pgvector, MinIO, and optional Ollama. Structured audit logging and rate limiting built in.
📄 Multi-Format Ingestion: PDF, Office documents, Markdown, plain text — parsed, chunked, and embedded automatically
⚡ Real-Time Processing: Background ingestion with live progress updates via SignalR
🎛️ Runtime Configuration: Change chunking strategy, embedding model, and search settings per container without restart
☁️ Cloud Identity Linking: Azure AD (OAuth2+PKCE) identity linking. Per-user AWS permission filtering is in progress — search is not yet filtered by cloud permissions
👥 Invite-Only Access: Admin-controlled user registration with four roles (Admin / Editor / Viewer / Agent)
🤖 Agent Management: Dedicated agent entities with API key lifecycle, scoped permissions, and audit trails
📋 Audit Logging: Structured audit trail for uploads, deletes, container operations, and auth events
📦 CLI Distribution: Native self-contained binaries (Windows/Linux/macOS) and .NET global tool via NuGet
🔄 Cross-Model Search: Switch embedding models mid-project — automatic Semantic→Hybrid fallback for legacy vectors
AI agent developers who need a knowledge backend their agents can both query and build — upload research, curate a corpus, and search it via MCP or REST API
.NET / Azure teams who want a RAG platform that fits their existing stack and cloud identity
Enterprise teams who need project-isolated knowledge bases with proper RBAC and audit trails
Anyone tired of re-uploading files — point Connapse at your existing Amazon S3/Azure Blob Storage/filesystem storage
This project is in active development (v0.3.2) and approaching production-readiness.
v0.3.x adds cloud connector architecture, multi-provider embeddings and LLM support, Azure AD cloud identity linking, and rate limiting.
✅ Authentication and authorization (v0.2.0)
✅ Role-based access control (Admin / Editor / Viewer / Agent)
✅ Audit logging
✅ Cloud identity linking — Azure AD OAuth2+PKCE (v0.3.0)
⚠️ No per-user search filtering — any user who can reach a container can search every document in it. Cloud permissions are not yet enforced on search; see SECURITY.md
✅ Rate limiting — built-in ASP.NET Core middleware with per-user and per-IP policies (v0.3.2)
⚠️ Set a strong Identity__Jwt__Secret in production — see deployment guide
See SECURITY.md for the full security policy.
┌──────────────────────────────────────────────────────────────────────┐
│ Access Surfaces │
│ Web UI (Blazor) │ REST API │ CLI │ MCP Server │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Core Services Layer │
│ Document Store │ Vector Store │ Search │ Ingestion │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Connectors Layer │
│ MinIO │ Filesystem │ Amazon S3 │ Azure Blob Storage │
└─────────────┬────────────────────────────────────────────────────────┘
│
┌─────────────▼────────────────────────────────────────────────────────┐
│ Infrastructure │
│ PostgreSQL+pgvector │ MinIO (S3) │ Ollama (optional) │
└──────────────────────────────────────────────────────────────────────┘[Upload] → [Parse] → [Chunk] → [Embed] → [Store] → [Searchable]
↓
[Metadata]
↓
[Document Store]Target: < 30 seconds from upload to searchable.
Key Technologies:
Database: PostgreSQL 17 + pgvector for vector embeddings
Object Storage: Managed Storage abstraction — MinIO (S3-compatible) by default, overridable per deployment
Backend: ASP.NET Core 10 Minimal APIs
Frontend: Blazor Server (interactive mode)
Embeddings: Ollama (default), OpenAI, Azure OpenAI (configurable)
LLM: Ollama, OpenAI, Azure OpenAI, Anthropic (configurable)
Search: Hybrid vector + keyword with convex combination fusion
Connectors: Managed Storage (MinIO default), Filesystem, Amazon S3, Azure Blob Storage
Architecture Guide - System design and component overview
API Reference - REST API endpoints and examples
Connectors Guide - Connector types, configuration, and background sync
AWS Setup - Roles Anywhere access, IAM Identity Center, S3 Access Grants, troubleshooting
Azure Identity Setup - Azure AD OAuth2+PKCE integration
Deployment Guide - Docker and production setup
Security Policy - Security limitations and roadmap
Contributing Guidelines - How to contribute
Connapse is pre-1.0. Major design work is tracked in Discussions.
✅ Document ingestion pipeline (PDF, Office, Markdown, text)
✅ Hybrid search (vector + keyword with convex combination fusion)
✅ Container-based file browser with folders
✅ Web UI, REST API, CLI, MCP server
✅ Three-tier auth: Cookie + Personal Access Tokens + JWT (HS256)
✅ Role-based access control (Admin / Editor / Viewer / Agent)
✅ Invite-only user registration (admin-controlled)
✅ First-class agent entities with API key lifecycle
✅ Agent management UI + PAT management UI
✅ Audit logging (uploads, deletes, container operations)
✅ CLI auth commands (auth login, auth whoami, auth pat)
✅ GitHub Actions release pipeline (native binaries + NuGet tool)
✅ 256 passing tests (unit + integration)
✅ 4 connector types: Managed Storage (MinIO default, provider-abstracted), Filesystem (FileSystemWatcher), Amazon S3 (IAM-only), Azure Blob Storage (managed identity)
✅ Per-container settings overrides (chunking, embedding, search, upload)
✅ Cloud identity linking: Azure AD (OAuth2+PKCE)
↩️ AWS IAM Identity Center (device auth flow) — shipped in v0.3.0, since removed (#435): the device flow could not carry a per-user identity through to a token
⚠️ IAM-derived scope enforcement — built but never wired into search (#422); cloud permissions do not filter results today
✅ Multi-provider embeddings: Ollama, OpenAI, Azure OpenAI
✅ Multi-provider LLM: Ollama, OpenAI, Azure OpenAI, Anthropic
✅ Multi-dimension vector support with partial IVFFlat indexes per model
✅ Cross-model search: automatic Semantic→Hybrid fallback for legacy vectors
✅ Background sync: FileSystemWatcher for local, 5-min polling for cloud containers
✅ Connection testing for all providers (Amazon S3, Azure Blob Storage, MinIO, LLM, embeddings, Azure AD)
✅ 457 passing tests (unit + integration)
✅ Input validation hardening: filename length, path depth, control characters, search params, agent fields
✅ Security fixes: empty API key auth bypass, path traversal, security headers middleware
✅ Unified upload pipeline (IUploadService) shared by API and MCP
✅ File type allowlist for uploads
✅ Rate limiting middleware (per-user and per-IP)
✅ Bulk MCP tools: bulk_upload and bulk_delete
✅ CLI improvements: files commands, container stats, --pre updates, --help flags
✅ Self-hosted fonts (no CDN dependencies)
✅ Docker release package on ghcr.io
v0.4.0: Per-user AWS search permissions via Amazon Cognito identity linking (#436); communication connectors (Slack, Discord)
v0.5.0: Knowledge platform connectors (Notion, Confluence, GitHub)
v1.0.0: Production-ready stable release
Does Connapse require internet access? — No. Use Ollama for fully offline embeddings and search.
How many documents can it handle? — Thousands per container. Built on PostgreSQL + pgvector.
Which MCP clients work with Connapse? — Any client supporting Streamable HTTP transport — Claude Desktop, Claude Code, VS Code, Cursor, and others.
Is my data private? — Fully self-hosted. With Ollama, nothing leaves your machine. Cloud providers (OpenAI, Azure) are optional.
What embedding providers are supported? — Ollama (local), OpenAI, and Azure OpenAI. Switch at runtime without re-deploying.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Quick contribution checklist:
Fork the repo and create a feature branch
Follow code conventions in CONTRIBUTING.md
Write tests for new features (xUnit + FluentAssertions)
Ensure all tests pass: dotnet test
Update documentation if needed
Submit a pull request
Good first issues: Check issues labeled good-first-issue
This project is licensed under the MIT License - see LICENSE for details.
You are free to:
✅ Use commercially
✅ Modify
✅ Distribute
✅ Sublicense
✅ Use privately
The only requirement is to include the copyright notice and license in any substantial portions of the software.
📖 Documentation: docs/
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
🔒 Security Issues: See SECURITY.md
Built with:
.NET - Application framework
Blazor - Web UI
PostgreSQL + pgvector - Vector database
MinIO - S3-compatible object storage
Ollama - Local LLM inference
⭐ If you find this project useful, please star the repository to show your support!
Delete up to 100 files in one call. Returns per-file success/failure results.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileIds | Yes | JSON array of file (document) IDs to delete, e.g. ["id1","id2"]. Max 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral details beyond the destructiveHint annotation, such as the batch limit and per-file result format.
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 purpose and limits, 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?
Given no output schema, description compensates by noting per-file results. Covers key constraints (limit, return format). Could mention error handling for missing files, but sufficient.
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 already describes both parameters fully (100% coverage). The description does not add new semantic value beyond what the schema provides.
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 action (delete), resource (files), and limits (up to 100, one call), distinguishing it from single-file deletion and bulk upload.
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?
Implies usage for deleting multiple files up to 100, but lacks explicit when-to-use vs alternatives or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload up to 100 files in one call. Each file is parsed, chunked, and embedded. Returns per-file results.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| files | Yes | JSON array of file objects. Each object: {"filename":"name.txt", "content":"...", "encoding":"text|base64", "folderPath":"/optional/"}. Max 100. |
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 the processing pipeline (parse, chunk, embed) but lacks details on error handling for partial failures, file size limits, or supported formats. Adequate but not comprehensive.
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, no filler. Every sentence provides essential information: capacity, processing, and return type.
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?
No output schema exists, so description should clarify return values. 'Returns per-file results' is vague; could specify status, errors, or IDs. Also missing constraints like file size, timeout, or authentication requirements.
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 coverage is 100%, both parameters are documented. The description adds 'Max 100' which reinforces the schema's 'max 100' constraint in files parameter description, but no new meaning beyond 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 uses specific verb 'Upload' with resource 'files', states the limit 'up to 100', and explains the processing pipeline ('parsed, chunked, and embedded'). It clearly distinguishes from sibling 'upload_file' which handles single files.
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 bulk usage via 'up to 100 files' but does not explicitly state when to use this over single upload or alternatives like 'search_knowledge'. No when-not or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new container for organizing documents. Use when setting up a new knowledge domain or project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Container name (lowercase alphanumeric and hyphens, 2-128 chars) | |
| description | No | Optional description for the container |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states creation purpose, lacking details on permissions, side effects, or duplicate handling. Adequate but minimal.
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 clear sentences, front-loaded with action, 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?
No output schema, and description does not mention return value (e.g., created container info). Adequate for simple tool but incomplete on expected response.
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 has 100% coverage with descriptions for both parameters. Description repeats the same meaning, adding no extra value. Baseline 3.
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?
Clearly states action (create), resource (container), and purpose (organizing documents). Distinguishes from sibling tools like container_delete or container_list.
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 says 'Use when setting up a new knowledge domain or project', providing clear context. Does not mention exclusions or alternatives, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a container. MinIO containers must be emptied first. Filesystem/S3/Azure files are not deleted — only the index is removed.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds important behavioral details: files are not deleted, only the index is removed, and MinIO containers must be emptied first.
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 concise sentences, front-loaded with the action and followed by key constraints, with 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 simple tool with one parameter and no output schema, the description covers the essential behavior, prerequisites, and what is not deleted, though it could mention irreversibility.
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 coverage is 100%, and the description does not add additional meaning beyond the schema's parameter description.
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 deletes a container, and differentiates from sibling tools like delete_file by clarifying that files are not deleted, only the index.
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?
It specifies a prerequisite (MinIO containers must be emptied) and clarifies what is not affected, but does not explicitly compare to alternatives like bulk_delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all containers with document counts. Use to discover available knowledge bases before searching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat these. It adds the return of document counts, but lacks details on pagination or performance. With annotations covering safety, this is adequate.
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 two sentences (12 words) that are front-loaded and contain no fluff. Every word earns its place.
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 parameters and no output schema, the description covers the tool's purpose and usage context well. It mentions 'document counts,' giving insight into return data, but could be slightly more detailed on output format.
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?
No parameters exist, so schema coverage is 100%. The description adds no parameter info, which is appropriate. Baseline 4 for 0 parameters.
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 it lists all containers with document counts and specifies its use for discovering knowledge bases before searching. This differentiates it from sibling tools like container_stats or container_create.
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 says 'Use to discover available knowledge bases before searching,' providing clear context for when to use it. It lacks explicit exclusion guidance but is sufficient given the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get container statistics: document counts, chunk count, storage size, and embedding model info.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds value by specifying the exact statistics returned, providing context beyond what annotations offer. No contradictions.
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, front-loaded sentence that efficiently conveys the tool's purpose and output details with 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 simple, read-only tool with one parameter and no output schema, the description fully covers what the tool returns and its use case, making it complete.
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 provides full coverage for the single parameter (containerId) with a clear description. The tool description does not add additional semantic meaning for the parameter, so baseline 3 is appropriate.
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 container statistics' and lists specific data (document counts, chunk count, storage size, embedding model info), making it distinct from siblings like container_list which only list container IDs or names.
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 the tool is for retrieving statistics of a specific container but does not explicitly state when to use it over alternatives or provide exclusions. No guidance on prerequisites (e.g., container must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file and all its chunks and vectors. To update a file, delete it first then re-upload with upload_file.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileId | Yes | File (document) ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true. The description adds value by specifying that chunks and vectors are also deleted, giving a fuller scope of the operation's effects. It does not contradict annotations.
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 concise sentences: first clearly states the purpose, second provides a practical usage tip. No fluff, front-loaded, every sentence earns its place.
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 destructive tool with full schema coverage and an annotation, the description adequately covers the deletion scope and provides an update workflow hint. It could mention irreversibility or permissions, but these are implied by the destructive hint. Overall sufficient.
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 already documents both parameters (containerId and fileId) with descriptions, achieving 100% coverage. The description does not add extra semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.
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 'Delete a file and all its chunks and vectors', which specifies the verb (delete) and resource (file and associated data). It also distinguishes from siblings like bulk_delete by implying single-file deletion via the fileId parameter, and provides additional context about updating.
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 includes explicit guidance for updating: 'To update a file, delete it first then re-upload with upload_file.' However, it does not explicitly warn against using this tool for bulk deletions or when to prefer bulk_delete, though the parameterization hints at single-file usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a document's full text by ID or path. Returns extracted text for binary formats (PDF, DOCX, PPTX).
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| fileId | Yes | Document ID (UUID) or virtual path (e.g., '/docs/readme.md') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds that it returns extracted text for binary formats (PDF, DOCX, PPTX) beyond what annotations convey.
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 front-loaded sentences, no waste, clearly communicate purpose and key behavior.
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 retrieval tool with 2 required parameters, description covers purpose, return value (full text, extraction for binaries). Lacks error handling or response format, but sufficient for typical use.
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 coverage is 100% with good descriptions for both parameters. Description restates 'by ID or path' but adds no new semantic detail beyond 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?
Description clearly states verb 'Retrieve' and resource 'document's full text', specifies query by ID or path, and mentions handling of binary formats. Distinguishes from siblings like list_files (metadata) and search_knowledge.
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?
Implied usage context as a read-only retrieval tool, but no explicit when-to-use or alternatives (e.g., 'for metadata use list_files'). Clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and folders at a path within a container. Use to browse container contents before retrieving documents.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| path | No | Folder path to list (default: root '/') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the browsing context but does not disclose additional behavioral traits such as pagination or error handling, which would provide further transparency.
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 extremely concise with two sentences: one for the core function and one for usage guidance. Every word is necessary and no information is redundant.
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 two parameters and no output schema, the description is fairly complete. It covers what the tool does and when to use it, though it could mention the return structure (e.g., list of file names) to be fully self-contained.
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 100%, so the baseline is 3. The description does not add any parameter details beyond what the schema already provides for containerId and path.
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 a specific verb 'list' and specifies the resource 'files and folders at a path within a container'. It also provides context by stating its use case 'before retrieving documents', which distinguishes it from siblings like get_document, upload_file, and delete_file.
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 advises using this tool to browse container contents before retrieving documents, giving clear context. However, it does not explicitly exclude other uses or mention alternatives beyond the implied contrast with get_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a container using semantic, keyword, or hybrid mode. Returns ranked document chunks with scores. Use when answering questions from stored knowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query text | |
| containerId | Yes | Container ID or name to search within | |
| mode | No | Search mode: Semantic (vector), Keyword (full-text), or Hybrid (both). Default: Hybrid | |
| topK | No | Number of results to return. Default: 10 | |
| path | No | Optional: Filter results to a folder subtree (e.g., '/docs/') | |
| minScore | No | Minimum similarity score floor (0.0-1.0). Defaults to 0.05. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the main behavioral traits are covered. The description adds 'Returns ranked document chunks with scores,' which gives some extra context but is not critical. No destructive behavior or auth needs are mentioned, but annotations suffice.
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 two sentences long, with the first sentence covering purpose and behavior, and the second giving usage guidance. Every sentence adds value, and there is no unnecessary text.
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 100% schema coverage, the presence of annotations, and no output schema, the description is fairly complete. It covers purpose, usage, and return type. However, it could briefly mention that results are from the specified container, but that is implicit in the first sentence.
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 coverage is 100%, with each parameter having a description in the input schema. The tool description does not add any additional information about the parameters beyond what the schema already provides, so baseline 3 is appropriate.
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 action ('Search a container') and specifies the modes (semantic, keyword, hybrid). It also mentions the return type ('ranked document chunks with scores'), making the tool's purpose distinct from siblings like container_list or 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 explicitly suggests using the tool 'when answering questions from stored knowledge,' providing a clear use case. However, it does not mention when not to use it or compare to alternatives, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to be parsed, chunked, embedded, and made searchable. Provide either 'content' (base64) or 'textContent' (raw text), not both.
| Name | Required | Description | Default |
|---|---|---|---|
| containerId | Yes | Container ID or name | |
| content | No | Base64-encoded file content. For binary files (PDF, DOCX, images). Mutually exclusive with textContent. | |
| textContent | No | Raw text content for text-based files (Markdown, TXT, CSV, JSON, etc.). Mutually exclusive with content. | |
| fileName | No | Original file name with extension | |
| path | No | Destination folder path (e.g., '/docs/2026/') | |
| strategy | No | Chunking strategy: Semantic, FixedSize, or Recursive. Default: Semantic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It mentions the processing pipeline (parse, chunk, embed) and mutual exclusivity of content types, but does not disclose failure modes, idempotency, permissions, or response format. This is adequate but not rich.
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 with no waste. The purpose is front-loaded, and essential usage hint is included. Every sentence adds value.
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?
With 6 parameters (1 required), schema covers all, and no output schema, the description is fairly complete. It explains the overall goal and key constraint. However, it omits details on return value or confirmation. Still, it is adequate for an agent to understand and use the tool.
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 coverage is 100%, so baseline is 3. The description reiterates the mutual exclusivity of content and textContent already in schema descriptions, adding minimal extra meaning. No new parameter semantics 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 clearly states the action ('Upload a file') and the resource, and describes the processing pipeline ('parsed, chunked, embedded, and made searchable'). This distinguishes it from sibling tools like bulk_upload (multiple files) and delete_file (deletion).
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 gives a parameter usage guideline ('Provide either content or textContent, not both') but lacks explicit guidance on when to use this tool over siblings like bulk_upload or search_knowledge. No when-not-to-use or alternative recommendations are provided.
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.3.2bulk_deletebulk_uploadcontainer_createcontainer_deletecontainer_listcontainer_statsdelete_fileget_documentlist_filessearch_knowledgeupload_fileEach tool targets a distinct operation: container management, file operations, bulk actions, and search. No two tools have overlapping purposes; even delete_file and bulk_delete are clearly scoped by single vs batch.
All tools follow a consistent verb_noun snake_case pattern (e.g., container_create, upload_file, search_knowledge). No mixed conventions or vague verbs.
11 tools is well-scoped for a knowledge management server, covering container CRUD, file operations, bulk operations, and search. No redundancy or missing essential operations.
Covers most lifecycle operations: container create/list/delete, file upload/get/list/delete, bulk upload/delete, and search. Missing container update and folder creation, but these are minor gaps that agents can work around.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Destrayon/Connapse'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
