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.

Variable	Type	Default	Description
ARCA_APP_HOST	str	0.0.0.0	Server bind address
ARCA_APP_PORT	int	4201	Server port
ARCA_APP_WORKERS	int	1	Uvicorn worker count
ARCA_APP_AUTH_KEY	str	required	Bearer token for MCP authentication
ARCA_TRANSPORT	str	streamable-http	MCP transport (stdio, http, sse, streamable-http)
ARCA_DEBUG	bool	false	Enable debug mode
ARCA_LOG_MESSAGE_MAX_LEN	int	2000	Maximum log message length
ARCA_GOOGLE_API_KEY	str	required	Google API key for Gemini embeddings
ARCA_EMBEDDING_MODEL	str	gemini-embedding-001	Gemini embedding model name
ARCA_EMBEDDING_DIMENSION	int	3072	Embedding vector dimensionality
ARCA_VECTOR_STORE_PATH	str	./lancedb	LanceDB storage directory
ARCA_REDIS_HOST	str	localhost	Redis host
ARCA_REDIS_PORT	int	6379	Redis port
ARCA_REDIS_DB_CACHE	int	4	Redis database number for cache
ARCA_REDIS_PASSWORD	str	null	Redis password (optional)
ARCA_CACHE_TTL	int	3600	Default cache TTL in seconds (1 hour)
ARCA_CACHE_TTL_LONG	int	604800	Long cache TTL in seconds (7 days, used for embeddings)

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.

Parameter	Type	Required	Description
content	str	yes	Content to store
bucket	str | null	no	Bucket name (defaults to "default")

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

memory_get

Retrieve memories via semantic similarity search.

Parameter	Type	Required	Description
query	str	yes	Natural language search query
bucket	str | null	no	Filter by bucket
top_k	int	no	Number of results (default: 5)

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

memory_delete

Delete a specific memory by its UUID.

Parameter	Type	Required	Description
memory_id	str	yes	UUID of the memory to delete

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

memory_clear

Clear all memories in a bucket.

Parameter	Type	Required	Description
bucket	str | null	no	Bucket to clear (defaults to "default")

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.

Method	Path	Description
POST	/v1/memories	Add a memory
POST	/v1/memories/search	Semantic similarity search
DELETE	/v1/memories/{memory_id}	Delete a specific memory
DELETE	/v1/memories?bucket=...	Clear memories in a bucket
GET	/v1/buckets	List all buckets

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

Method	Path	Description
GET	/	Index — returns { "message": "OK" }
GET	/health	Health check — returns status, version, uptime, exec ID
GET	/docs	Interactive OpenAPI documentation
*	/app/mcp	MCP streamable-http endpoint

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