A few months ago, I was sitting in my IDE attempting what should have been a 10-minute task: writing an asynchronous checkout webhook inside our order-service using an AI coding assistant.

The prompt seemed simple:

"Listen for payment.succeeded, update order state, check inventory in inventory-service, and notify the customer."

The AI produced syntactically spotless code. But under the hood, it was completely broken:

  • It guessed that inventory-service had an endpoint called /api/inventory/check with { "item_id": str, "qty": int }. In reality, inventory was a Go service listening on a Kafka topic inventory.reserve with UUID keys.

  • It assumed our PostgreSQL orders table had a status enum column. In reality, order statuses lived in a separate order_transitions audit table.

  • It refactored an internal helper that altered a shared event payload, completely unaware that analytics-pipeline and notification-service would crash in production the moment this deployed.

That was my breaking point. We didn't have an LLM intelligence problem—we had a context topology problem.

I call it the Microservices Context Paradox: AI models can reason through complex logic, but the moment you drop them into a distributed architecture, they operate completely blindfolded.

To fix this for my own workflows, I built ArchMCP.

The 3 Failure Modes of AI in Distributed Repos

When you build microservices, your system isn't one repo—it's 15 to 30 services written across Go, TypeScript, Python, and Java.

Before building ArchMCP, I watched developers cycle through three exhausting workarounds:

1. The "Human Clipboard" Tax

You want your AI in payment-service to call user-service. You stop coding, open the other repo, copy Pydantic models or TypeScript types, paste them into your prompt, and type: "Here is the contract, write the client." You're no longer engineering—you're acting as a manual clipboard courier between repositories.

2. Context Dumping (200k Tokens of Noise)

Teams try cloning every repo into one massive workspace or stuffing thousands of lines into 200k-token windows. The result? High latency, soaring token bills, and attention dilution. When an LLM has 150,000 tokens of unrelated code dumped into context, subtle foreign keys and route signatures get lost in the noise.

3. The "Silent Blast Radius" Catastrophe

In a monolith, your compiler immediately warns you if a change breaks a caller. In microservices, altering /api/v1/orders won't trigger a single compiler error in order-service, but it will quietly dismantle downstream consumer services you didn't even know existed.

How I Architected ArchMCP

I didn't want another static documentation site or an outdated architecture wiki. Architecture changes on every commit.

I wanted my AI assistant—running in Cursor, Claude Desktop, VS Code, or Google Antigravity—to dynamically inspect, query, and reason about our entire microservice ecosystem at runtime via the Model Context Protocol (MCP).

┌─────────────────────────────────────────────────────────────┐
│  AI Assistant (Cursor / Claude Desktop / Antigravity IDE)   │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP over SSE (Remote / Local)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                       🏛️ ArchMCP Hub                         │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   Polyglot AST Parser  │    │  In-Memory Graph Index  │  │
│  │ (FastAPI, Gin, Prisma, │    │ (Routes, DBs, Queues,   │  │
│  │  NestJS, Spring Boot)  │    │  Docker Topologies)     │  │
│  └────────────────────────┘    └─────────────────────────┘  │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │ Blast Radius Analyzer  │    │  Mermaid Flow Generator │  │
│  └────────────────────────┘    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1. Zero Manual Config: Automated Discovery (archmcp scan)

Nobody maintains architecture YAML files. With archmcp scan ./my-project, ArchMCP traverses your codebase and uses static AST parsing to extract:

  • Routes & APIs: FastAPI, Express, NestJS, Spring Boot, Gin, Rails.

  • Database Models: SQLAlchemy, Django, Prisma, TypeORM, Mongoose, GORM.

  • Event Topologies: Kafka topics, SQS, RabbitMQ, and Redis pub/sub producers and consumers.

  • Dependencies: Docker Compose networks and cross-service HTTP client calls.

2. Just-In-Time Architecture Queries

Instead of pre-loading 100k tokens of code upfront, ArchMCP exposes 12 fine-grained, read-only MCP tools that the AI queries on demand:

  • search_microservices("stripe payment"): Finds the owning service in milliseconds.

  • find_api_owner("/v1/subscriptions"): Instantly resolves the host service and controller.

  • get_database_schema("inventory-service"): Pulls exact table columns without opening the inventory repository.

  • get_full_context_package("payment-service"): Assembles a compact, token-optimized context bundle tailored for code generation.

3. Automated Blast Radius Protection

Before letting an AI refactor an endpoint, it calls analyze_blast_radius("order-service"). ArchMCP traverses the dependency graph and returns direct callers and transitive consumers:

$ archmcp blast-radius order-service
Direct Callers:    gateway-service, mobile-bff
Transitive Flow:   payment-service -> analytics-pipeline
Event Subscribers: [order.created] -> notification-service, warehouse-service

If a proposed refactor alters an event schema, the AI warns me before writing a single line of breaking code.

What Changes in Daily Development

Once I wired ArchMCP into my IDE via .agents/mcp_config.json and .cursor/mcp.json, the friction disappeared:

  • Zero Context Switching: The AI queries ArchMCP in the background and writes integration code that works on the first test run.

  • Token Efficiency: Instead of dumping 50k tokens of raw code into prompts, ArchMCP returns dense, structured JSON metadata (averaging ~400 tokens per tool call).

  • Safe Refactoring: I can prompt: "Generate a sequence diagram for our checkout flow and verify what breaks if we deprecate /api/v1/orders/cancel." The AI invokes generate_sequence_diagram and analyze_blast_radius and hands me a verified impact report.

Try It in Your Own Stack

I built ArchMCP to be open-source, fast, and enterprise-ready—running locally via CLI or as a central remote MCP server with salted HMAC-SHA256 authentication and RBAC.

git clone https://github.com/ShubhamScript/archmcp.git
cd archmcp
pip install -e .
archmcp scan ./my-microservices
archmcp run

Then point Cursor, Claude Desktop, or Antigravity to http://localhost:8000/sse and give your AI assistant genuine architectural vision.

Feedback or questions? Feel free to ask here.