🏛️ ArchMCP: Central Remote MCP Server for Microservices

Give your AI coding assistant an organizational brain.
ArchMCP is a lightweight, remote Model Context Protocol (MCP) server that connects your AI assistants (Google Antigravity, Claude Desktop, Cursor, VS Code) to your entire microservice architecture in real time.

📚 Read the Step-by-Step User Manual & Setup Guide

---

📖 The Story Behind ArchMCP

The Everyday Problem

Imagine you are writing a feature in order-service with your AI coding assistant. You ask the AI:

"Implement checkout and charge the customer."

Immediately, the AI hits a wall:

• It has no idea what headers payment-service requires for idempotency.
• It doesn't know what database columns exist in inventory-service to reserve stock.
• It has no clue which upstream services will break if you modify an endpoint.

To fix this today, developers usually try one of two bad options:

1. Dumping entire repositories into the prompt: This easily wastes 100,000+ tokens per question, costs a lot of money, makes the AI slow, and causes hallucinations due to prompt clutter.
2. Cloning 20+ repos locally: Every developer on the team has to keep 20 repos updated on their laptop just so their local AI has context.

---

The Solution: A Shared Remote Brain

ArchMCP solves this by acting as a centralized, sub-millisecond architecture brain.

Instead of running as a private local command on one laptop, ArchMCP runs as a shared remote service. Any engineer on your team connects their AI assistant to the ArchMCP server URL with an authentication token.

When your AI assistant needs to know:

• "Which service handles refunds?" $\rightarrow$ It calls search_microservices.
• "What tables does payment-service own?" $\rightarrow$ It calls get_database_schema.
• "If I change /api/v1/orders, who breaks?" $\rightarrow$ It calls analyze_blast_radius.

┌────────────────────────────────────────────────────────┐
│                   AI Assistant Client                  │
│       (Google Antigravity, Claude Desktop, Cursor)     │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │  HTTP / Server-Sent Events (SSE)
                           │  Authorization: Bearer <token>
                           │
┌──────────────────────────▼────────────────────────────────────────────────────────┐
│                                   ArchMCP Server                                   │
│                                                                                    │
│   ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐   │
│   │      MCP Tools      │  │    MCP Resources    │  │       MCP Prompts        │   │
│   │ • search_services   │  │ • arch/overview     │  │ • cross_service_planner  │   │
│   │ • blast_radius      │  │ • services/catalog  │  │ • incident_triage        │   │
│   │ • sequence_diagram  │  │ • guidelines/docs   │  │ • contract_refactor      │   │
│   │ • get_db_schema     │  │ • service docs      │  │                          │   │
│   └──────────┬──────────┘  └──────────┬──────────┘  └────────────┬─────────────┘   │
│              │                        │                          │                 │
│   ┌──────────▼────────────────────────▼──────────────────────────▼─────────────┐   │
│   │                       Microservice Intelligence Engine                     │   │
│   │ • Transitive Graph Traversal & Blast Radius Analyzer (BFS)                 │   │
│   │ • In-Memory Index & Token Search (< 2ms response time)                     │   │
│   │ • Dynamic OpenAPI / Swagger 3.0 Importer                                   │   │
│   └───────────────────────────────────┬────────────────────────────────────────┘   │
│                                       │                                            │
│   ┌───────────────────────────────────▼────────────────────────────────────────┐   │
│   │              Embedded Web Visualizer & Live Sandbox (/dashboard)           │   │
│   │ • Interactive Service Topology Explorer & Token Economics Calculator       │   │
│   └────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────┘

---

💡 How I Designed It & Why

When designing ArchMCP, the goal was to keep it fast, clean, and practical without unnecessary complexity:

1. Why Remote HTTP/SSE instead of a local CLI process?

Standard MCP servers run as a local stdio subprocess. While that works for single-user desktop scripts, a company with 50 engineers working across 30 microservices needs one central source of truth. By hosting ArchMCP over HTTP/SSE, architectural updates and new API schemas are instantly available to everyone without local repository cloning.

2. Why In-Memory Graph Indexing instead of a Heavy Vector Database?

Many AI tools immediately jump to heavy vector databases (like Pinecone or Milvus). For structured architecture metadata (API routes, database tables, and service dependencies), graph traversal and fast lexical token matching are:

• Deterministic: Exact matches for routes like /api/v1/auth/login or table users.
• Zero Overhead: Runs with ~38 MB of RAM and zero external API keys or GPU requirements.
• Blazing Fast: Sub-2ms response time.

3. Trade-offs Considered

Approach	The Good	The Bad	The Decision
Local CLI (stdio)	Simple for one person.	Everyone has to clone every repo locally; no centralized updates.	Skipped
Custom REST API	Familiar web endpoints.	Requires writing and maintaining custom plugins for every IDE.	Skipped (MCP is the open standard)
Heavy Vector DB	Semantic search.	Slow cold-starts, high cost, requires embeddings infrastructure.	Deferred for simple in-memory graph index
Remote MCP over SSE	Centralized, instant sync, authenticated, works with all major AI tools.	Requires running a lightweight server.	Adopted ✅

---

📊 Performance Benchmarks & Token Economics

We measured the difference between asking an AI assistant to analyze a microservice task by dumping repository context vs querying ArchMCP:

Benchmark Metric	Full Codebase Prompting	ArchMCP Query (Live)	Efficiency Gain
Token Consumption	~140,000 to 180,000 tokens	~120 to 380 tokens	> 99.6% Reduction
Execution Latency	N/A (Full file scans / manual)	~1.8 ms to 16 ms	Sub-second real-time
Memory Footprint	~500 MB (Local clones + indexers)	~38 MB	> 90% Less RAM
Test Suite	N/A	18/18 Passing in < 1.5s	Instant verification

💡 Real-Time Verification: You can test and observe these performance metrics live at any time using the built-in Interactive Dashboard Sandbox, which calculates query latency and token savings on every request.

---

🔍 Surprises & Discoveries Along the Way

Building a remote MCP server in Python revealed a few fascinating technical details:

1. Type Hints Become AI Schemas: The official Python MCP SDK automatically reads Python type annotations and docstrings to generate JSON-Schema definitions that the LLM uses to pick tools. Good docstrings literally make the AI smarter.
2. DNS Rebinding Guard: The MCP 2.0 protocol automatically validates incoming Host headers to protect internal developer networks from browser-based DNS attacks.
3. The 2-Phase SSE Handshake: When an AI client connects to GET /sse, the server opens the event stream and returns a unique session postback URL (/messages/?session_id=...). All subsequent JSON-RPC tool calls are posted to this session.

---

🖥️ Live Browser Visualizer & Sandbox

ArchMCP includes an embedded, responsive web dashboard at http://localhost:8000/dashboard (or /):

• Interactive Topology: Click any service card (auth-service, order-service, payment-service) to inspect its APIs, owned database tables, and dependency mapping.
• Live Tool Sandbox: Test any MCP tool in real time and see the JSON-RPC request/response with live token savings and latency metrics.

---

⌨️ Developer CLI

ArchMCP comes with a handy command-line tool:

# 1. Start the Remote Server
archmcp run

# 2. Explore the Catalog in your Terminal
archmcp explore

# 3. Calculate Change Blast Radius
archmcp blast-radius auth-service

# 4. Import a live OpenAPI / Swagger Specification
archmcp import-openapi https://petstore.swagger.io/v2/swagger.json --owner "Commerce Team"

---

🔌 Connecting Your AI Assistant

Once ArchMCP is running (e.g. at http://127.0.0.1:8000/sse), configure your AI tool in seconds:

Google Antigravity IDE

Add to .agents/mcp_config.json:

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse?token=dev-token-secret-123"
    }
  }
}

---

🚀 3-Step Quickstart

# 1. Clone & Install
git clone https://github.com/ShubhamScript/archmcp.git
cd archmcp
pip install -e .[dev]

# 2. Run Tests
pytest -v

# 3. Start Server
archmcp run

Open http://localhost:8000/dashboard in your browser to explore your architecture interactively.

---

🔮 What's Next on the Roadmap

If expanding ArchMCP for 500+ microservices in a large enterprise:

1. Semantic Concept Search: Adding pgvector or sqlite-vec with local embeddings so developers can ask conceptual questions ("Where does recurring billing live?").
2. Backstage Integration: Auto-syncing from Spotify's Backstage catalog-info.yaml.
3. Redis Event Bus: Synchronizing active SSE sessions across horizontally scaled container replicas.
4. Git Webhooks: Automatically updating schemas whenever a PR merges.

---

📂 Project Structure

archmcp/
├── README.md                      # Project guide & architecture story
├── pyproject.toml                 # Dependencies, CLI scripts, and build config
├── Dockerfile                     # Container build instructions
├── docker-compose.yml             # Container orchestration
├── data/
│   └── repositories.yaml          # Sample microservices catalog
├── src/
│   └── archmcp/
│       ├── main.py                # Server bootstrap
│       ├── cli.py                 # Developer CLI (run, explore, blast-radius, import-openapi)
│       ├── config/settings.py     # Environment settings
│       ├── auth/                  # Bearer token verification & ASGI middleware
│       ├── mcp/                   # Tools, Resources, Prompts, and SSE route handlers
│       ├── services/              # Blast radius, graph traversal, and search logic
│       ├── ingestion/             # OpenAPI importer, markdown parser, dependency scanner
│       ├── storage/               # In-memory database & token search index
│       ├── web/                   # Embedded visualizer and live testing playground
│       └── models/                # Pydantic schemas (Architecture, BlastRadius, Services)
└── tests/                         # 18 unit & integration tests

---

📄 License

MIT License. Free for open source and commercial use.