MCP Tool Specification

The server ships as @cloud-arch/mcp-server on npm — npx -y @cloud-arch/mcp-server. It registers five tools.

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 at web.cloud-arch.ru/workspace/api.

Diagram links in successful results

Both create_diagram and update_diagram return the canonical viewer URL and a floating-window launcher URL. MCP clients that support resource links can render both as clickable links; the same URLs also appear in the text and structured result.

Structured field	Meaning
`url`	Backward-compatible alias of `viewerUrl`
`viewerUrl`	Canonical viewer URL, for example `https://web.cloud-arch.ru/v/my-web-app`
`floatingWindowUrl`	One-click launcher URL, for example `https://web.cloud-arch.ru/v/my-web-app?launch=pip`
`floatingWindow`	Launch metadata: Document PiP mode, browser activation requirement, live updates, and opener-tab requirement

Chrome requires transient user activation before it can create a Document Picture-in-Picture window, so navigation alone cannot open it automatically. Open floatingWindowUrl, then click Open floating window or press Enter on the focused button. Keep the opener tab open while you work so the floating diagram can continue receiving live updates.

The floating canvas also enables node dragging, alignment guides, and undo. The rearranged layout is saved locally in that browser; moving a node does not rewrite the diagram through MCP or change what other viewers see. Ordinary embed URLs remain presentation-only unless they explicitly request layout interaction.

create_diagram

Create an interactive architecture diagram on CloudArch. Provide a natural-language description and get back the canonical viewer URL plus the floating-window launcher URL.

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`	Yes	The CloudArch script. Call `get_script_template` first — it carries the layout rules, the scenario API and the architectural patterns. Must use TopologyBuilder/FlowBuilder globals, call `await topology.apply()`, and end with `return flow;`. No `import`/`export`
`readme`	`string`	No	Markdown README rendered in the viewer’s README pane. Strongly recommended: without it the pane shows an empty card. Target 150-400 words, sections `## Overview` / `## Components` / `## Scenarios` / `## Tradeoffs` / `## References`. Use `:concept{slug="..."}` and `:case{slug="..."}` inside prose; `::concept{slug="..."}` and `::case{slug="..."}` are leaf directives and work only on their own line. Use exact public slugs with matching sections. Link gallery (`explore`) diagrams normally to `/v/<slug>`; never leave a dead badge
`tags`	`string[]`	No	Tags for categorization. Defaults to `["mcp-generated"]`
`isPublic`	`boolean`	No	Whether the diagram is publicly visible. Defaults to `false` — a diagram built from someone’s codebase does not land in the public gallery unless you pass `true` deliberately

Example

create_diagram({
  description: "Three-tier web app with Nginx, Node.js API, PostgreSQL, and Redis cache",
  slug: "my-web-app",
  code: "const topology = new TopologyBuilder(true);\n... \nreturn flow;",
  readme: "## Overview\n..."
})

Returns the diagram ID and slug together with the canonical and floating-window URLs.

Before the request is sent, the server runs validateScriptStructure on code. Structural errors abort the call and come back as a report instead of a URL; warnings are appended to a successful response.

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
`readme`	`string`	No	Updated Markdown README — same authoring guide as on `create_diagram`
`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..."
})

Returns the updated diagram ID and slug together with the canonical and floating-window URLs. The floating viewer receives saved revisions while its opener tab remains open.

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