Arca

A Model Context Protocol (MCP) server providing semantic memory storage and retrieval via vector embeddings. Built with FastAPI + FastMCP, using LanceDB for vector storage and Google Gemini for embedding generation.

Features

• Semantic Search — Store and retrieve memories using natural language queries powered by vector similarity search
• Dual Access — MCP tools for AI agents + REST API for programmatic integrations
• Knowledge Graph — Connect memories with directed, labelled edges and traverse them
• Multi-Tenant Isolation — Namespace-scoped operations via X-Namespace HTTP header
• Bucket Organization — Group memories into logical buckets for structured storage
• JSON Canvas Export — Render a bucket's memories and connections as a JSON Canvas document
• Document Ingestion (optional add-on) — Chunk and store whole documents (txt/md, plus PDF/DOCX/HTML/EPUB/FB2 via per-format extras) through the arca-ingest package (uv sync --extra ingest), exposed as POST /v1/ingest and the memory/ingest tool
• Embedding Caching — Redis-backed cache for generated embeddings to minimize API calls
• Bearer Token Auth — Constant-time token verification for secure access

Prerequisites

• Python 3.14+
• UV package manager
• Redis
• Google API key (for Gemini embeddings)

Quick Start

# Clone the repository
git clone https://github.com/m0nochr0me/arca-mcp.git
cd arca-mcp

# Install dependencies
uv sync --locked

# Configure environment — create a .env with at least the required secrets
cat > .env <<'EOF'
ARCA_APP_AUTH_KEY=your-secret-bearer-token
ARCA_GOOGLE_API_KEY=your-google-api-key
EOF

# Run the server
python -m app

The server starts on http://0.0.0.0:4201 by default, with the MCP interface at /app/mcp and the REST API at /v1. See Configuration for all available settings.

Docker

# Build (core, no add-ons)
docker build -t arca-mcp .

# Build with the document-ingestion add-on (txt/md only)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest -t arca-mcp .

# Build with ingestion + every format loader (PDF/DOCX/HTML/EPUB/FB2)
docker build --build-arg ARCA_INSTALL_EXTRAS=ingest-all -t arca-mcp .

# Run
docker run -p 4201:4201 \
  -e ARCA_APP_AUTH_KEY=your-secret-key \
  -e ARCA_GOOGLE_API_KEY=your-google-api-key \
  -e ARCA_REDIS_HOST=host.docker.internal \
  arca-mcp

The Docker image uses Python 3.14 slim with UV for dependency management. Mount a volume at ARCA_VECTOR_STORE_PATH (default ./lancedb) to persist data across container restarts.

ARCA_INSTALL_EXTRAS selects an optional extra to install at build time: ingest for the base add-on (txt/md), or ingest-all for the add-on plus all format parsers. The build arg takes a single extra name — not a pkg[extra] specifier like ingest[all].

MCP Client Configuration

Example .mcp.json for connecting an MCP client (e.g., Claude Code):

{
  "mcpServers": {
    "arca_memory": {
      "type": "http",
      "url": "http://localhost:4201/app/mcp",
      "headers": {
        "Authorization": "Bearer <your-auth-key>",
        "X-namespace": "my_namespace"
      }
    }
  }
}

<your-auth-key> must match ARCA_APP_AUTH_KEY. The X-namespace header scopes all operations to a tenant (defaults to "default" if omitted).

Documentation

In-depth reference material lives in doc/:

• Configuration — all ARCA_ environment variables and their defaults
• MCP Tools — the memory/* tool reference (add, get, graph traversal, …)
• REST API — /v1/* endpoint reference with curl examples
• Architecture — request flow, module layout, key patterns, tech stack

License

See LICENSE.