Model Context Protocol (MCP) Server
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server in Archivum acts as a universal bridge between AI agents and the self-hosted knowledge base. It allows compliant AI clients—such as Claude Desktop, Cursor, and VS Code—to programmatically read, search, and update the wiki, as well as perform complex queries and ingestion tasks. By exposing Archivum's core capabilities as standardized tools, the MCP server enables the "wiki that writes itself" by allowing agents to maintain persistent knowledge across sessions.
Sources: archivum-prd-v1.0.md:12-16, README.md:12-15
Architecture and Transports
The MCP server is built using the Python FastMCP framework and is designed to be compatible with a wide range of AI clients through two primary transport mechanisms.
Transport Modes
The server supports both stdio and HTTP/SSE transports to accommodate different client requirements:
- stdio: Used by desktop-local applications that launch the server as a subprocess.
- HTTP/SSE (Server-Sent Events): Used by web-based clients or remote agents. In Docker-based deployments, the SSE transport typically exposes port
8001.
Sources: apps/backend/archivum/mcp/server.py:270-282, README.md:231-235, archivum-prd-v1.0.md:329-335
Connection Flow
The following diagram illustrates how external AI clients interact with the Archivum MCP Server:
The diagram shows the dual-transport entry points leading to a unified tool dispatcher that interacts with Archivum's primary storage layers.
Sources: apps/backend/archivum/mcp/server.py:35-43, archivum-prd-v1.0.md:337-345
Available MCP Tools
The server exposes several tools that provide programmatic access to Archivum's core features.
| Tool Name | Description | Key Inputs |
|---|---|---|
ingest_source | Processes a file path or URL into the wiki. | source, wiki_id |
search_wiki | Performs semantic search across all wiki content. | query, top_k |
get_page | Retrieves full markdown content by page slug. | slug |
list_pages | Lists all pages within a specific wiki. | wiki_id |
write_page | Creates or updates a wiki page and triggers re-indexing. | title, content, tags |
query | Asks a question and receives a synthesized answer with citations. | question |
graph_neighbors | Explores the knowledge graph by returning neighbors of a node. | node_id |
lint_wiki | Runs a health check for broken links and contradictions. | wiki_id |
life_daily_note | Creates or returns a structured daily note. | day |
Sources: apps/backend/archivum/mcp/server.py:46-177, README.md:273-284
Tool Implementation Details
Ingestion and Synthesis
The ingest_source tool utilizes the project's ingestion pipeline to parse documents and URLs. It streams progress events back to the client via a callback mechanism. The query tool combines semantic search via Qdrant with LLM synthesis (via Anthropic, OpenRouter, or OpenAI-compatible providers) to generate answers grounded in the wiki's content.
Sources: apps/backend/archivum/mcp/server.py:46-60, apps/backend/archivum/mcp/server.py:180-224
Life OS Integration
Archivum includes specialized "Life OS" tools to manage personal productivity data:
life_daily_note: Manages the creation of daily logging pages.life_register_project: Registers new projects and creates canonical project wiki pages.life_create_task: Creates tasks that can be linked to specific wiki pages or projects.
Sources: apps/backend/archivum/mcp/server.py:114-142, Progress.md:27-28
Graph Interaction
The graph_neighbors tool queries the Kuzu embedded graph database to visualize relationships.
This sequence shows the retrieval of localized graph data for agent-led knowledge exploration.
Sources: apps/backend/archivum/mcp/server.py:145-152, apps/backend/archivum/mcp/demo.py:84-100
Configuration and Deployment
The MCP server relies on environment variables for security and provider configuration.
| Variable | Description | Default |
|---|---|---|
MCP_API_KEY | Bearer token required for authentication. | Required |
MCP_PORT | Port for the SSE transport. | 8001 |
LLM_SYNTHESIS_MODEL | Model used for answering queries (e.g., claude-sonnet-4-6). | claude-sonnet-4-6 |
LLM_SYNTHESIS_PROVIDER | Provider for query synthesis (e.g., anthropic, ollama). | anthropic |
Sources: README.md:144-165, apps/backend/archivum/mcp/server.py:28-33
Client Configuration Snippet
To connect a client like Claude Desktop, users provide a configuration similar to the following:
{
"mcpServers": {
"archivum": {
"command": "docker",
"args": ["exec", "-i", "archivum-mcp", "python", "-m", "archivum.mcp.server", "--stdio"],
"env": { "MCP_API_KEY": "your-secret-key" }
}
}
}
Sources: README.md:237-248, archivum-prd-v1.0.md:347-355
Summary
The MCP Server is the primary interface for AI-driven maintenance of the Archivum knowledge base. By supporting both local (stdio) and remote (SSE) transports, it ensures that tools like semantic search, graph navigation, and source ingestion are available to any modern AI assistant, effectively turning the wiki into an agentic "second brain."