SirThomasRipley/archon-mcp-server

Archon MCP Server

A lightweight MCP (Model Context Protocol) server microservice for the Archon knowledge management system.

Overview

This MCP server provides tools and protocol handling for AI assistants to interact with the Archon system. It communicates with other Archon services via HTTP and exposes MCP tools for:

• RAG queries and knowledge base search
• Code example retrieval
• Project and task management (when enabled)
• Source management

Deployment on Railway

Manual Railway Deployment

1. Fork this repository

2. Create a new project on Railway

3. Connect your GitHub repository

4. Add the following environment variables:

   • SUPABASE_URL: Your Supabase project URL
   • SUPABASE_SERVICE_KEY: Your Supabase service key
   • SERVICE_AUTH_KEY: A secure key for service-to-service authentication
   • ARCHON_SERVER_URL: URL of the main Archon server (e.g., http://archon-server.railway.internal:8181)
   • ARCHON_AGENTS_URL: URL of the agents service (e.g., http://archon-agents.railway.internal:8052)
   • LOGFIRE_TOKEN (optional): For observability

5. Deploy!

Local Development

Prerequisites

• Python 3.11+
• pip or uv package manager

Setup

1. Clone the repository:

git clone https://github.com/yourusername/archon-mcp-server.git
cd archon-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Copy .env.example to .env and configure:

cp .env.example .env
# Edit .env with your configuration

4. Run the server:

python -m src.mcp_server.mcp_server

The server will start on http://localhost:8051

Docker Build

Build the Docker image:

docker build -t archon-mcp .

Run with Docker:

docker run -p 8051:8051 --env-file .env archon-mcp

Health Check

The server exposes a health endpoint at /health which returns:

• 200 OK: Server is healthy
• 503 Service Unavailable: Server is unhealthy or dependencies are unavailable

Architecture

This is a lightweight microservice that:

• Uses HTTP-based communication with other Archon services
• Implements the MCP protocol for AI assistant integration
• Maintains minimal dependencies (~150MB container size)
• Supports horizontal scaling

Environment Variables

License

MIT