---
id: kb-012
title: Technical Documentation - MCP Server (atoms-mcp-prod)
scope:
  type: project
  id: 4sgm
purpose: technical-documentation-mcp
tags:
  - mcp
  - server
  - architecture
  - documentation
topics:
  - engineering
  - python
  - mcp-protocol
version: 1
created: 2025-11-26
updated: 2025-11-26
author: droid-agent
status: final
related_ids:
  - kb-010
  - kb-011
external_refs: []
---

# Technical Documentation - MCP Server (atoms-mcp-prod)

## Architecture Overview

Atoms MCP is a Model Context Protocol (MCP) server built on FastMCP that provides AI agents with powerful tools for knowledge management, entity tracking, and workflow automation.

### System Architecture
- **Framework**: FastMCP 2.13.1.
- **Runtime**: Python 3.12, ASGI (Starlette 0.50).
- **Deployment**: Vercel (serverless) + Local development.
- **Infrastructure**: Supabase (PostgreSQL), Upstash Redis (Caching), Google Vertex AI (Embeddings).
- **Authentication**: Hybrid (OAuth PKCE for web + Bearer tokens for API).

---

## Agent-Optimized Tools (Consolidated)

The server exposes 5 consolidated tools to simplify agent reasoning and reduce decision overhead:

1. **workspace_operation**: Manages active context (organization, project, document).
2. **entity_operation**: CRUD and search operations on documents, requirements, and tasks.
3. **relationship_operation**: Manages the entity graph (linking, unlinking, querying).
4. **workflow_execute**: Executes multi-step transaction workflows.
5. **data_query**: Unified search (FTS, Semantic, Hybrid) and statistical aggregations.

---

## Core Services

| Service | Purpose |
|---------|---------|
| **hybrid_search** | Combines BM25 keyword search with Vertex AI vector embeddings. |
| **relationship_engine** | Handles graph operations and change impact analysis. |
| **permission_middleware** | Enforces RBAC and Supabase Row-Level Security (RLS). |
| **concurrency_manager** | Manages asynchronous locking and parallel operations. |
| **embedding_factory** | Orchestrates embedding generation and aggressive caching. |

---

## Search Capabilities

- **Semantic**: Vector similarity via Vertex AI (high accuracy).
- **Keyword**: Fast BM25 text search (exact matches).
- **Hybrid**: Combined approach with configurable scoring weights.
- **Auto**: Intelligently selects the best search mode based on query characteristics.

---

## Installation & Deployment

1. **Environment**: Python 3.12 is required.
2. **Setup**: `uv pip install -e .` or `pip install .`.
3. **Configuration**: Set up `.env` with Supabase, WorkOS, Upstash, and Vertex AI keys.
4. **Run**: `python cli.py server start` (starts on port 8000).
5. **Deploy**: `vercel deploy` for serverless hosting.
