Connapse
Connapse’s MCP server gives agents one interface to search and manage a knowledge base, keep sourced agent memory, and explore indexed code.
Search containers or sources with hybrid, semantic, or keyword modes, filtering by path, topK, and minimum score.
Read one document or up to 50 documents at once; list folder contents with sorting/pagination; inspect container descriptions, lists, and statistics.
Upload single or bulk files, append text to existing files, and delete files individually or in bulk.
Create and delete containers, and list/describe/search them.
Create personal or team memory spaces; remember facts with dates, reasons, and sources; recall current/historical facts; correct facts while keeping history; view timelines; permanently forget facts.
Navigate indexed C#/Python/TypeScript code: find symbols, find references/callers/subtypes, assess change impact, and map repository hotspots.
Use read-only/idempotent query tools and destructive-hinted delete/forget tools through MCP.
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.
Connapse is a self-hosted knowledge base for AI agents. Point it at your files, SFTP servers, S3 buckets, Azure Blob containers, GitHub repositories, Confluence spaces and Jira projects, and agents reach all of it through an MCP server (the Model Context Protocol, the standard way agents call outside tools) or a REST API. It is RAG with hybrid search and reranking, agent memory that keeps dated facts with their sources, and results that can be trimmed to what each person can open in the source system. It is open source, runs on your own machine with Docker, and is built on .NET 10, PostgreSQL and pgvector.
Who it's for: teams and developers who want Claude, Cursor, VS Code or their own agents to work from the company's documents, tickets and code, without sending that data to a hosted service.
Quick start
You need Docker with Compose 2.34 or later, about 8 GB of free memory and port 5001 free.
docker compose -f oci://ghcr.io/destrayon/connapse:compose up -d -yThat's the whole setup: nothing to clone and no file to edit. Connapse makes its own passwords and downloads its embedding model on the first start. Open http://localhost:5001, create the owner account, make a container, upload a document or a whole folder, and search it. You get passages from your documents, each labelled with the file it came from. The Quickstart walks through each step.
The install guide covers other embedding providers, GPUs, the optional reranker and running from a clone.
Related MCP server: mnemostack
Connect an agent
In Connapse, open Admin → Agents, create an agent, and give it an API key. Then add Connapse to your MCP client. For Claude Code:
claude mcp add --transport http connapse http://localhost:5001/mcp --header "X-Api-Key: cnp_your_key"Connect an MCP client has the setup for Claude Code, Claude Desktop, VS Code and Cursor, and Connect Claude to Connapse is a step-by-step tutorial.
What your agent gets
23 named MCP tools, plus 3 generic tools that reach the rest of the REST API. Each key only gets the tools its scopes allow, and deletes over MCP can wait for your approval.
Group | Tools | What they do |
Search and documents |
| Search a container or source, read whole documents, and add or remove files |
Memory |
| Pick a personal or team memory space, keep dated facts there with their sources, recall them in a later session, and correct them without losing history |
Code |
| Find definitions and callers in indexed C#, TypeScript and Python, and see what a change could affect |
Containers |
| List, inspect, create and delete containers |
Approvals |
| Learn whether you approved or denied a held call, and why, so the agent carries on by itself |
Every tool and its parameters are in MCP tools.
Features
Hybrid search with reranking
Every search runs vector search and keyword search together and fuses the two rankings, so exact names and paraphrased questions both find their passages. An optional cross-encoder reranker re-scores the top results. See About search and Tune search.
Memory for agents
An agent saves what it learns as a fact: a subject, an attribute and a value, with the dates it was true and the documents it came from. Every fact goes into a memory space the agent names: a personal space only you and your agents see, or a team space everyone sees, and the agent is told who will see it. A later session recalls it. A correction keeps the old value in history, and forgetting deletes every version. A fact is shown only to people who can read every source it cites, and the Memory page shows each space's facts and their history. See About agent memory.
Connect your data
Upload files or whole folders, or index them where they live: SFTP servers (including the folders on your own computer), Amazon S3, Azure Blob Storage, GitHub (Markdown docs, or issues and pull requests), Confluence and Jira. Anything else can connect through a custom source server you write against an open protocol. Each container has its own files, vector index and settings. See Connect your data and file types.
The Providers page lists the built-in providers next to any custom source server you add.
Search trimmed to what each person can open
Results from GitHub, Confluence, Jira and custom sources are checked against each reader's own access in the source system, through their linked account. S3 and Azure Blob get the same check once an admin switches on per-user permissions for that provider; until then, everyone who can search a container sees all of it. When filtering is on, a person, or an agent acting for them, never sees a passage they couldn't open in the original, and when the check can't be made the result is left out. See Permissions, Amazon S3 and Azure Blob Storage.
Linked results
Records point at each other, and Connapse stores those links: a GitHub issue with the pull request that closes it, a Jira issue with its epic, parent and the Confluence pages it mentions, and code with its definitions, imports and calls. With link search turned on (it is off by default), a search also brings back what its best results link to, checked against the same permissions. See Following links.
Run fully local with Ollama
By default, Ollama runs alongside Connapse, so embeddings are computed on your machine and nothing leaves it. OpenAI or Azure OpenAI can be swapped in from Settings at runtime, without a restart. See Change the embedding model.
Built on .NET 10, PostgreSQL and pgvector
A Blazor Server web UI, a REST API, the MCP server and the connapse CLI all sit on one ASP.NET Core app, with PostgreSQL and pgvector for search and MinIO for uploads. See How Connapse works.
Search quality
Measured with Connapse's retrieval eval on enterprise-v1: 50,000 documents from EnterpriseRAG-Bench and 470 questions. nDCG@10 scores how well the top 10 results are ordered, from 0 to 1.
Configuration | nDCG@10 |
Hybrid search, fusion weight 0.75, no reranker (the earlier default) | 0.565 |
Adding the | 0.660 |
Adding the reranker and today's default fusion weight, 0.65 | 0.677 |
The fusion weight sets how much the vector side counts against the keyword side. The runs are in the fusion research note, a per-slice breakdown is in the retrieval weaknesses note, and the harness is in tests/Connapse.Eval.
Documentation
The full documentation is in docs/.
Get started: run Connapse and search your first document
Self-host: install, production, backups, upgrades and troubleshooting
Connect your data: sources from S3, Azure, GitHub, Atlassian, SFTP and your own systems
Guides: users, tokens, agents, the API and search tuning
Concepts: how Connapse, search, ingestion and permissions work
Reference: REST API, MCP tools, configuration, roles and scopes, file types and error types
Support
Bugs: GitHub Issues
Ideas and questions: GitHub Discussions
Security issues: see SECURITY.md
Contributing
Contributions are welcome. Start with CONTRIBUTING.md and Development, and look for issues labeled good-first-issue.
License
MIT.
Available Tools
24 toolsappend_to_fileA
Add text to the end of an existing text file (.md, .txt, .log, ...) and reindex it. The text goes on exactly as given, so start it with a newline to put it on a new line. The file keeps its ID, path and added date; appends to one file through this server at once all land.
Inputs: file (required), text (required), containerId (required).
code_find_symbolARead-onlyIdempotent
Find where a function, method, class or other symbol is defined in indexed code (C#, Python, TypeScript). match="exact" (default) takes a name as far as you know it: "Post", "Ledger.Post" or "Acme.Billing.Ledger.Post". match="words" takes words that all appear in the qualified name ("ledger post"). match="meaning" takes a description ("where invoices are written to the ledger"). With follow=true, also returns what the first definition calls, constructs or inherits and the files defining those: the files to read to see how it works. Returns definitions with path, start and end line and signature, and ranked files.
Inputs: query (required), containerId (required), limit, match, +1 more.
code_impactARead-onlyIdempotent
What a change to a symbol could affect: the functions and types that call or inherit it, directly or through others, up to depth hops, with the files that hold them and which of those are tests. For a type, what uses its members counts too. Only links the code index resolved are followed; a call it could not resolve is missed, so check code_references for the full list of mentions.
Inputs: symbol (required), containerId (required), depth, limit.
code_referencesARead-onlyIdempotent
Find the files that use a symbol, best evidence first: files the code index links to it (a call, a base type, an import) with the lines, then files whose text names it. kind="calls" for callers only, "inherits" for subtypes only, "all" (default) for every use and mention. Name the symbol as for code_find_symbol ("Ledger.Post"); qualify it further when the name is common.
Inputs: symbol (required), containerId (required), kind, limit.
code_repo_mapARead-onlyIdempotent
A map of indexed code: the files the rest of the code refers to most, each with its main definitions and how many other files use each. Start here in an unfamiliar repository, or pass path to map one folder.
Inputs: containerId (required), path, maxFiles.
container_createA
Create a new container for documents. Use when setting up a new knowledge domain or project. To make a place for memory facts, use memory_space_create instead.
Inputs: name (required), kind, description.
container_deleteADestructive
Delete a container. It must be emptied first, because deleting one deletes its stored files. External sources are not containers and cannot be deleted here. If your token asks before deleting, nothing is deleted yet: the call returns a deletion batch that Connapse carries out itself once your owner approves it. Read the outcome with deletion_status; don't repeat the call.
Inputs: containerId (required).
container_describeARead-onlyIdempotent
Returns an agent-optimized description of a knowledge scope — container or source: its description and document statistics. Use this to understand what a scope covers before querying via search_knowledge, or when container_list output is insufficient to choose between them. The response also echoes the server's tool-routing instructions for clients that don't surface them on connect.
Inputs: containerId (required).
container_listARead-onlyIdempotent
Lists every searchable knowledge scope with its description and document count. Each entry is kind=managed (storage Connapse owns, browsable with list_files) or kind=source (an external system Connapse mirrors read-only — searchable, but it has no file listing). Memory spaces are not listed here: memory_spaces lists them. Use to discover what exists when the target is unknown; if the user already named one, call search_knowledge on it directly instead.
Inputs: no named parameters.
container_statsARead-onlyIdempotent
Get container statistics: document counts, chunk count, storage size, and embedding model info.
Inputs: containerId (required).
delete_fileADestructive
Delete one file, or up to 100 with 'fileIds', and all their chunks and vectors. To update a file, delete it first then re-upload with upload_file. With 'fileIds' it returns per-file success/failure results. If your token asks before deleting, nothing is deleted yet: the call returns a deletion batch that Connapse carries out itself once your owner approves it. Read the outcome with deletion_status; don't repeat the call. A held batch holds at most 50 files.
Inputs: containerId (required), fileId, fileIds.
deletion_statusARead-onlyIdempotent
Check a batch of deletions, by its id: one you asked for with request_deletions, or one a held delete call returned. Pass waitSeconds (up to 50) to wait while it is pending or running. state is pending, expired, denied, running or done; each item's state is deleted, skipped (gone or changed since you asked), failed, not_approved or denied, and its outcome says why. message says what to do next.
Inputs: batchId (required), waitSeconds.
get_documentARead-onlyIdempotent
Retrieve a document's full text by ID or path, or up to 50 documents' with 'files'. Returns extracted text for binary formats (PDF, DOCX, PPTX). Intended for use after search_knowledge returns a DocumentId worth reading in entirety, or when the user has named an exact file. With 'files' each document comes under its own header in the order asked; a file that can't be read gets an error line and doesn't stop the others, and past 2,000,000 characters in all, the rest get one too. Pair 'files' with list_files sort "newest" and limit to read the newest entries of a folder in two calls.
Inputs: containerId (required), files, fileId.
list_filesARead-onlyIdempotent
Lists folder entries and document IDs at a path within a container (does NOT return file contents — for content questions, use search_knowledge). Intended for inventory requests such as 'what files exist in X' or when the user named a specific filename. Large listings return a soft error directing you to search_knowledge; override with confirmLarge: true or paginate with limit. Each file shows when it was added and, if since changed, when it was updated. For the newest N entries of a folder, pass sort: "newest" and limit: N, then read them all with get_documents.
Inputs: containerId (required), path, sort, limit, +1 more.
memory_correctA
Replace a fact and keep the old one in history. kind="changed": the world changed, so the old fact ends on validFrom and the new value starts there (validFrom required). kind="wrong": the old fact was never right, so it is marked superseded and the new value takes its dates; a date you pass replaces the old one, except one where another version of the fact starts or ends. Subject and attribute default to the old fact's. A fact with versions you cannot see (another user's private ones) cannot be corrected; remember a new fact instead.
Inputs: value (required), factId (required), kind, reason, +6 more.
memory_forgetADestructive
Delete a fact for good, with every earlier and later version of it from corrections. Nothing of it is kept. To record that a value changed, use memory_correct instead. If your token asks before deleting, nothing is deleted yet: the call returns a deletion batch that Connapse carries out itself once your owner approves it. Read the outcome with deletion_status; don't repeat the call.
Inputs: factId (required), containerId.
memory_recallARead-onlyIdempotent
Read facts from memory: what is true now, or on a past date with asOf. Name a space to read one space, or leave it out to read every space you can see. Filter by subject or attribute, or pass a question as query. Each fact comes with its space, whether it is personal (only you see it) or team, its dates, author and sources. Use includeHistory to also get ended and corrected facts (for "which ticket changed X" or "when did X change"). Reading one named space without asOf or attribute returns nextCursor when there are more facts: pass it back as cursor for the next page.
Inputs: asOf, limit, query, space, +5 more.
memory_rememberA
Store one fact in a memory space: a subject ("Halcyon"), an attribute ("database") and a value ("PostgreSQL 15"), with the date it became true and the documents you learned it from. Name a space that exists: memory_spaces lists yours, and memory_space_create makes one if none fits. No space is made for you. Save to a personal space if it is about the user, their preferences or their own work; to a team space if it would be true and useful for others. If unsure, ask. Cite the document IDs that search_knowledge or get_document gave you: a fact citing sources is shown only to people who can read all of them. The answer says who can see what you saved. When a value you stored before has changed, call memory_correct instead. If the answer lists facts already current with the same subject and attribute, and you meant to replace one, correct it instead of leaving both.
Inputs: value (required), subject (required), attribute (required), space, +5 more.
memory_space_createA
Make a memory space to save facts in. Kind "personal" is yours alone: only you see its facts. Kind "team" is seen by everyone in this Connapse. Save to a personal space if it is about the user, their preferences or their own work; to a team space if it would be true and useful for others. If unsure, ask. Check memory_spaces first: no space is made for you, so make one only when none fits. Names are lowercase letters, numbers and hyphens.
Inputs: kind (required), name (required), description.
memory_spacesARead-onlyIdempotent
List the memory spaces you can use: your personal spaces (only you see them) and team spaces (everyone in this Connapse sees them). Each comes with its id, name, kind, description, whether you can add to it, and who sees it. Call this before saving to pick a space for memory_remember; if none fits, make one with memory_space_create. At most 100 are returned; pass name to find others.
Inputs: kind, name.
memory_timelineARead-onlyIdempotent
A subject's facts in date order, ended and corrected ones included: how its values changed over time. Name a space to read one space, or leave it out to read every space you can see; each fact says which space it is in. With from/to, only the facts that started or ended in that window ("what changed between A and B"). Reading one named space without from, to or attribute returns the newest facts first a page at a time, each page in date order, with nextCursor when older facts remain: pass it back as cursor.
Inputs: to, from, limit, query, +5 more.
request_deletionsA
Ask your owner to approve several deletions at once: up to 50 items, each a file (kind "file", container, target = file id or path), a folder (kind "folder", container, target = folder path), an empty container (kind "container", container = its id or name), a memory space (kind "memory_space", container = the space's id or name) or a memory fact (kind "fact", target = the fact id), with a short reason the owner reads. Every item is checked now; if any can't be deleted nothing is asked, and the error names each bad item. Nothing is deleted yet: the owner approves all, some or none on the Approvals page, and Connapse then deletes the approved items itself, skipping any that are gone or changed since you asked. Call deletion_status with the returned id (and waitSeconds) to read each item's outcome; don't delete the items yourself.
Inputs: items (required).
search_knowledgeARead-onlyIdempotent
Search a container using semantic, keyword, or hybrid mode (Hybrid is the default and works well without tuning). Returns ranked passages with citations, scores, and document IDs. If the first query returns thin results, refine the query and call again.
Inputs: query (required), containerId (required), mode, path, +2 more.
upload_fileA
Upload one file, or up to 100 with 'files', to be parsed, chunked, embedded, and made searchable. For one file give 'fileName' and either 'content' (base64) or 'textContent' (raw text), not both.
Inputs: containerId (required), path, files, content, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools are cleanly separated by resource+action (container_list vs memory_spaces vs list_files, code_find_symbol vs code_references vs code_impact), and descriptions explicitly cross-reference siblings to steer selection. Two soft overlaps remain: container_stats vs container_describe both return description/document statistics, and delete_file (which accepts up to 100 fileIds) vs request_deletions both delete in batch, forcing the agent to reason about which path applies.
A clear domain-prefix scheme is used for three of the five sub-areas (container_*, memory_*, code_*) with verb_noun forms inside each group. The document/deletion tools drop the prefix (upload_file, get_document, list_files, delete_file, search_knowledge) and deletion_status breaks into noun_noun, so it is readable and mostly predictable rather than uniform.
24 tools is at the heavy end, but the server spans four real sub-domains (containers, documents, memory facts, code index) plus an approvals flow, averaging roughly five tools each. Almost every tool earns its place, with the only redundancy being the container_stats/container_describe pair.
Lifecycle coverage is strong across every domain: containers (list/stats/describe/create/delete), documents (upload/get/list/append/delete), memory (spaces, create, remember, recall, correct, forget, timeline), code (map, find, references, impact), and async deletion with status polling. Remaining gaps are minor conveniences (container rename/update, file move/copy, direct memory_space_delete outside the approvals flow) that agents can work around.
Maintenance
Related MCP Connectors
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Related MCP Servers
- AlicenseAqualityBmaintenanceSelf-hosted memory and governance layer for AI coding agents. 28 MCP tools with hybrid search, structured knowledge capture, behavioral nudges, and git-native storage. Zero cloud dependencies.306Business Source 1.1
- AlicenseAqualityAmaintenanceDurable hybrid memory for AI agents. Combines vector search, BM25, temporal retrieval, and optional Memgraph knowledge graph via reciprocal rank fusion. 6 MCP tools: health, search, answer, feedback, graph_query, graph_add_triple. Self-hosted with Qdrant backend.7278 PyPI10Apache 2.0
- FlicenseNot gradedqualityDmaintenanceSelf-hosted RAG-powered knowledge base that surfaces context from structured notes and transcripts, exposing each project as an MCP tool.-
- AlicenseNot gradedqualityDmaintenanceSelf-hosted knowledge manager and MCP server that lets you organize snippets, questions, and documents via a web UI and exposes them to AI assistants for reading and writing.MIT