MCP Integration Overview

The cloud-arch MCP (Model Context Protocol) integration lets an AI assistant turn a real codebase into a shareable, animated diagram URL.

Two separate servers exist, and it matters which one you mean:

Both are also listed in the official MCP Registry as ru.cloud-arch/cloudarch and ru.cloud-arch/cloudarch-codeflow.

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 an assistant should read

To build the script, the caller extracts architectural signals from:

Output

create_diagram returns the diagram name, its URL, its ID and its visibility. If validateScriptStructure produced warnings they are appended; if it produced errors, the call returns the report instead of creating anything.

Current status

Connect over HTTP (no API key)

The API speaks MCP directly and authenticates over OAuth, so there is no key to create, copy or store on disk. Point your client at the URL and it opens a browser for you to sign in and approve the connection:

{
  "mcpServers": {
    "cloudarch": {
      "url": "https://api.cloud-arch.ru/mcp"
    }
  }
}

The client registers itself (Dynamic Client Registration), so nothing has to be configured on our side first. Approving a client grants exactly two things — create diagrams in your workspace, and list the ones you created — and revoking it later leaves your API keys untouched.

All five tools are available over HTTP: get_script_template, create_diagram, update_diagram, delete_diagram, list_diagrams. They run the same code as the REST API, so validation, quotas and workspace permissions behave identically whichever way you reach them.

Install from npm

@cloud-arch/mcp-server is published on the public npm registry — nothing to clone, nothing to build:

npx -y @cloud-arch/mcp-server        # run it directly
npm install -g @cloud-arch/mcp-server # or install the `cloudarch-mcp` binary

Add it to your MCP client (Claude Desktop, Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "cloudarch": {
      "command": "npx",
      "args": ["-y", "@cloud-arch/mcp-server"],
      "env": {
        "CLOUDARCH_API_KEY": "ca_your_key_here"
      }
    }
  }
}

Get an API key at web.cloud-arch.ru/workspace/api. That page shows the same config block with your key already filled in — copy it whole instead of pasting the key by hand.

The codebase analyzer

@cloud-arch/mcp-codeflow is a second, separate server. It reads a TypeScript project from disk with ts-morph and emits an animated diagram of a real call path, so it needs filesystem access to the project you point it at. It stores the result through the same API, so it takes the same key:

{
  "mcpServers": {
    "cloudarch-codeflow": {
      "command": "npx",
      "args": ["-y", "@cloud-arch/mcp-codeflow"],
      "env": {
        "CLOUDARCH_API_KEY": "ca_your_key_here"
      }
    }
  }
}

Run both side by side: codeflow derives the diagram from the code, cloudarch stores and publishes it. See Tool Specification for the exact tool schemas. Generation Guide is the design spec for the codebase-extraction pipeline — useful as a checklist for the assistant, not a description of server behaviour.