How do I use Arca MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Arca MCP search for my notes about the marketing strategy" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Arca MCP

Arca MCP

Features

Prerequisites

Quick Start

Configuration

MCP Tools

`memory_add`

`memory_get`

`memory_delete`

`memory_clear`

`memory_list_buckets`

REST API

Examples

Add a memory

Search memories

Delete a memory

Clear a bucket

List buckets

Other Endpoints

Docker

MCP Client Configuration

Architecture

Module Layout

Tech Stack

Resources

New MCP Servers

Latest Blog Posts

MCP directory API