MCP Integration Overview

The cloud-arch MCP (Model Context Protocol) server lets AI assistants read a real codebase and automatically generate a working cloud-arch script that visualizes the architecture it finds. The result is a shareable diagram URL with animated scenarios — no manual diagramming required.

The vision

Every production codebase already contains a machine-readable description of its architecture: Docker Compose files list services and their port bindings, Kubernetes manifests declare deployments and services, Spring Boot configs name their Kafka topics and data sources, Helm values encode replicas and resource limits.

The MCP server reads these artifacts, infers topology (what services exist, who connects to whom), and generates a cloud-arch script that reflects the real system — not a diagram someone drew once and forgot to update.

Real codebase                   MCP Server                    cloud-arch
─────────────                   ──────────                    ──────────
docker-compose.yml   ──parse──► extract services   ──gen──►  topology script
k8s/deployments/     ──parse──► extract replicas            + animation
application.yml      ──parse──► extract connections          scenarios
kafka-topics.yml     ──parse──► extract topics                    │
                                                                   ▼
                                                         diagram URL returned
                                                         to AI assistant

Why this is powerful

Diagrams that stay accurate

Traditional architecture diagrams are created once and drift immediately. When a new service is added or a connection changes, no one updates the diagram. With MCP integration, regenerating the diagram is a single command — it reads from the actual infrastructure definitions, not from memory.

Progressive documentation

A developer asks: “Show me the production Kafka topology.” The MCP server reads the K8s manifests, identifies all Kafka consumers and producers by their KAFKA_BOOTSTRAP_SERVERS env vars and topic configurations, and returns a fully animated diagram showing which services publish and consume which topics.

Architecture reviews

During code review, an AI assistant can generate a before/after diagram showing exactly which connections change in a pull request. A new service added in a PR shows up as a new node in the “after” diagram, with its edges clearly visible.

Onboarding

New engineers ask: “How does authentication work in this codebase?” The MCP server generates a diagram focused on the auth path — from the client through the API gateway, to the auth service, to the user database — with an animation scenario that walks through the JWT validation flow.

What the server reads

The MCP server extracts architectural signals from:

Output

The MCP tool returns:

1. A cloud-arch script (TypeScript) that can be pasted into the editor
2. A diagram URL (if the script is saved to the server)
3. A summary of what was found: N services, M connections, K Kafka topics

Current status

See Tool Specification for the exact MCP tool schema, and Generation Guide for how to implement the generation logic correctly.