Arca MCP

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
• Multi-Tenant Isolation — Namespace-scoped operations via X-Namespace HTTP header
• Bucket Organization — Group memories into logical buckets for structured storage
• 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/your-org/arca-mcp.git
cd arca-mcp

# Install dependencies
uv sync --locked

# Configure environment
cp .env.example .env
# Edit .env with your ARCA_GOOGLE_API_KEY and ARCA_APP_AUTH_KEY

# Run the server
python -m app

The server starts on http://0.0.0.0:4201 by default, with MCP available at /app/mcp and REST API at /v1.

Configuration

All settings are configured via environment variables with the ARCA_ prefix, or through a .env file.

MCP Tools

All tools are mounted under the memory namespace. Operations are scoped to the namespace provided via the X-namespace HTTP header (defaults to "default").

memory_add

Store content in memory with a vector embedding.

Returns: { "status": "Memory added", "memory_id": "<uuid>" }

memory_get

Retrieve memories via semantic similarity search.

Returns: { "status": "Memory retrieved", "results": [...] }

memory_delete

Delete a specific memory by its UUID.

Returns: { "status": "Memory deleted" }

memory_clear

Clear all memories in a bucket.

Returns: { "status": "Memories cleared" }

memory_list_buckets

List all buckets in the current namespace.

Parameters: None

Returns: { "buckets": ["default", "work", ...] }

REST API

All REST endpoints are under /v1, require a Authorization: Bearer <token> header, and accept an optional X-Namespace header (defaults to "default").

Interactive API docs are available at /docs when the server is running.

Examples

All examples assume the server is running at localhost:4201. Replace $TOKEN with your ARCA_APP_AUTH_KEY.

Add a memory

curl -X POST http://localhost:4201/v1/memories \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Namespace: my_project" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode", "bucket": "preferences"}'

{
  "status": "Memory added",
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Search memories

curl -X POST http://localhost:4201/v1/memories/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Namespace: my_project" \
  -H "Content-Type: application/json" \
  -d '{"query": "what theme does the user like?", "top_k": 3}'

{
  "status": "Memory retrieved",
  "results": [
    {
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "User prefers dark mode",
      "bucket": "preferences"
    }
  ]
}

Delete a memory

curl -X DELETE http://localhost:4201/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Namespace: my_project"

{
  "status": "Memory deleted"
}

Clear a bucket

curl -X DELETE "http://localhost:4201/v1/memories?bucket=preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Namespace: my_project"

{
  "status": "Memories cleared"
}

List buckets

curl http://localhost:4201/v1/buckets \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Namespace: my_project"

{
  "buckets": ["default", "preferences", "work"]
}

Other Endpoints

Docker

# Build
docker build -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.

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"
      }
    }
  }
}

Architecture

              ┌─ /app/mcp → FastMCP Auth → MCP Tool Handler  ─┐
Request → FastAPI                                             ├→ Gemini Embedding (Redis cache) → LanceDB
              └─ /v1/*    → Bearer Auth  → REST Router ───────┘
                                  ↑
                        X-Namespace header (multi-tenancy)

Module Layout

app/
├── __main__.py          # Uvicorn entry point
├── main.py              # FastAPI app, lifespan, MCP mount, REST router
├── api/
│   ├── deps.py          # Shared dependencies (auth, namespace extraction)
│   └── memory.py        # REST API router for memory operations
├── context/
│   └── memory.py        # MCP tool definitions (add, get, delete, clear, list_buckets)
├── core/
│   ├── config.py        # Pydantic BaseSettings with ARCA_ env prefix
│   ├── db.py            # LanceDB async connection management
│   ├── cache.py         # Redis cache wrapper
│   ├── ai.py            # Google Gemini AI client
│   └── log.py           # Loguru logging configuration
├── schema/
│   ├── memory.py        # REST API request/response models
│   └── status.py        # Response models (HealthCheckResponse, IndexResponse)
└── util/
    ├── embeds.py         # Embedding generation with Redis caching
    └── memory.py         # Core memory CRUD against LanceDB (PyArrow schema)

Tech Stack

• FastAPI — ASGI web framework
• FastMCP — Model Context Protocol server framework
• LanceDB — Serverless vector database
• Google Gemini — Embedding generation (gemini-embedding-001)
• Redis — Embedding cache layer
• Pydantic — Settings and data validation
• UV — Python package manager
• Loguru — Logging