MCP Tool Specification

The @cloud-arch/mcp-server package exposes five tools over the Model Context Protocol. This page documents each tool’s parameters, behavior, and example usage.

Installation

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

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

⚠️

All tools except get_script_template require a valid CLOUDARCH_API_KEY environment variable. Get one from web.cloud-arch.ru > Dashboard > API Keys.

create_diagram

Create an interactive architecture diagram on CloudArch. Provide a natural-language description and get back a URL to the live animated diagram.

Parameters

Parameter	Type	Required	Description
`description`	`string`	Yes	Natural language description of the system architecture to visualize
`name`	`string`	No	Display name for the diagram. Auto-generated from description if omitted
`slug`	`string`	No	URL slug (lowercase, hyphens only). Auto-generated if omitted
`code`	`string`	No	Custom CloudArch script code. If provided, used directly instead of auto-generating from the description. Must use TopologyBuilder/FlowBuilder globals, call `await topology.apply()`, and end with `return flow;`
`tags`	`string[]`	No	Tags for categorization. Defaults to `["mcp-generated"]`
`isPublic`	`boolean`	No	Whether the diagram is publicly visible. Defaults to `true`

Example

create_diagram({
  description: "Three-tier web app with Nginx, Node.js API, PostgreSQL, and Redis cache",
  slug: "my-web-app"
})

Returns the diagram URL (e.g. https://web.cloud-arch.ru/v/my-web-app) and its ID.

When code is omitted, the server auto-generates a script by matching known patterns in the description (databases, message queues, load balancers, etc.) and connecting them with appropriate protocols and icons.

update_diagram

Update an existing CloudArch diagram. Identify the diagram by either its UUID or slug.

Parameters

Parameter	Type	Required	Description
`id`	`string`	No*	The diagram UUID to update
`slug`	`string`	No*	The diagram slug to update. Resolved to an ID automatically
`code`	`string`	No	Updated script code
`name`	`string`	No	Updated display name
`description`	`string`	No	Updated description
`tags`	`string[]`	No	Updated tags
`isPublic`	`boolean`	No	Updated visibility

* Either id or slug must be provided.

Example

update_diagram({
  slug: "my-web-app",
  code: "const topology = new TopologyBuilder(false);\n..."
})

delete_diagram

Delete an existing CloudArch diagram by its UUID.

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The diagram UUID to delete

Example

delete_diagram({ id: "c67ee7b4-d090-4f31-8fa5-be3fe60697bd" })

list_diagrams

List diagrams owned by the authenticated user.

Parameters

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum number of results. Defaults to `10`

Example output

1. My Web App -- https://web.cloud-arch.ru/v/my-web-app (42 views) [id: c67ee7b4-...]
2. Kafka Pipeline -- https://web.cloud-arch.ru/v/kafka-pipe (18 views) [id: a1b2c3d4-...]

get_script_template

Returns the full CloudArch script generation prompt/template. Use this to understand the scripting API before calling create_diagram with custom code.

Parameters

None.

What it returns

A system prompt that covers:

TopologyBuilder and FlowBuilder usage
Group creation and nesting (parentGroup.addGroup())
Available node icons (server, database, container, load-balancer, etc.)
Edge direction rules (connect(A, B) = A dials B)
Animation with showMessage using [LABEL] prefixes (no emojis)
Complete examples for flat and nested group topologies

Use get_script_template first to learn the scripting API, generate the code yourself, then pass it as the code parameter to create_diagram. This gives you full control over the topology layout and animation.

Error handling

All tools return errors as text content messages, not exceptions:

Condition	Response
`CLOUDARCH_API_KEY` not set	Error message with link to get a key
API returns HTTP error	Error message with details from the server
`update_diagram` without `id` or `slug`	Error asking for one of the two identifiers
Slug not found in `update_diagram`	Error suggesting to run `list_diagrams`
Script validation failure (422)	Detailed error listing missing nodes, `.apply()` call, etc.

Typical workflow

Call get_script_template to get the scripting reference
Write a TopologyBuilder + FlowBuilder script (or let the LLM generate it)
Call create_diagram with the code parameter to publish the diagram
Iterate with update_diagram to refine the script
Use list_diagrams to find diagram IDs and URLs
Use delete_diagram to clean up

API Usage (Live)Generation Guide