Getting started¶

Seven steps take you from a connected MCP client to a rendered diagram in the editor. Each step includes JSON-RPC examples for Cursor, Claude Desktop, a custom HTTP client, or curl.

1. Connect a client¶

UML-MCP speaks the Model Context Protocol over stdio (local subprocess) or Streamable HTTP (e.g. the hosted Vercel endpoint). Pick the path that matches your environment.

{
  "mcpServers": {
    "uml-mcp": {
      "url": "https://uml-mcp.vercel.app/mcp"
    }
  }
}

{
  "mcpServers": {
    "uml-mcp": {
      "command": "python",
      "args": ["-u", "server.py"],
      "cwd": "/absolute/path/to/uml-mcp",
      "env": {
        "MCP_OUTPUT_DIR": "output"
      }
    }
  }
}

/plugin marketplace add https://github.com/antoinebou12/uml-mcp
/plugin install uml-mcp@uml-mcp-plugins

npm install -g @smithery/cli@latest
smithery auth login
smithery mcp add antoinebou12/uml --client cursor

curl -sN \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://uml-mcp.vercel.app/mcp

2. Generate your first diagram¶

Once the client is connected, call generate_uml with a diagram_type and a piece of code. The minimal Mermaid example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "generate_uml",
    "arguments": {
      "diagram_type": "mermaid",
      "code": "graph TD; A-->B; A-->C; B-->D; C-->D;"
    }
  }
}

The server replies with a structured payload like:

{
  "code": "graph TD; A-->B; A-->C; B-->D; C-->D;",
  "url": "https://kroki.io/mermaid/svg/...",
  "playground": "https://mermaid.live/edit#...",
  "content_base64": "PHN2ZyB4bWxucz0...",
  "source": "kroki"
}

Open url for an SVG, playground to tweak the source online, or decode content_base64 for an inline embed. Same diagram rendered live:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

3. URL/base64 vs save to disk¶

generate_uml has two modes:

• URL/base64 only: omit output_dir. You get url, playground, and content_base64. No file I/O. Required for serverless deployments (MCP_READ_ONLY=true rejects output_dir).
• Save to disk: pass output_dir. You get the same fields plus local_path. The server creates the directory if it doesn't exist.

{
  "name": "generate_uml",
  "arguments": {
    "diagram_type": "class",
    "code": "@startuml\nclass User\n@enduml",
    "output_dir": "./output"
  }
}

4. Validate before render¶

validate_uml runs a local check (no Kroki call) so you catch unsupported types or formats before paying for a network round-trip. With strict: true it adds extra Mermaid/D2 lints.

{
  "name": "validate_uml",
  "arguments": {
    "diagram_type": "mermaid",
    "code": "graph TD; A-->B;",
    "output_format": "svg",
    "strict": true
  }
}

A typical response:

{
  "valid": true,
  "errors": [],
  "suggestions": [],
  "backend": "mermaid",
  "diagram_type": "mermaid",
  "prepared_code": "graph TD; A-->B;",
  "strict": true
}

Use validate_uml on user-supplied snippets before generate_uml so a Kroki HTTP 400 becomes a clear validation error instead of an opaque failure.

5. Render multiple diagrams in one call¶

generate_uml_batch accepts up to MCP_BATCH_MAX_ITEMS (default 20) items in a single tool call. A failure in one item does not stop the batch: each result has its own index and either the rendered fields or an error.

{
  "name": "generate_uml_batch",
  "arguments": {
    "items": [
      { "diagram_type": "mermaid", "code": "graph LR; A-->B" },
      { "diagram_type": "class",   "code": "@startuml\nclass A\n@enduml" },
      { "diagram_type": "d2",      "code": "x -> y" }
    ],
    "output_dir": null
  }
}

Returns:

{
  "results": [
    { "index": 0, "url": "...", "source": "kroki" },
    { "index": 1, "url": "...", "source": "kroki" },
    { "index": 2, "url": "...", "source": "kroki" }
  ]
}

6. Customize output: format, theme, scale¶

Three parameters tune the rendered image:

{
  "name": "generate_uml",
  "arguments": {
    "diagram_type": "sequence",
    "code": "@startuml\n!theme cerulean\nA -> B: Hi\n@enduml",
    "output_format": "png",
    "theme": "cerulean",
    "scale": 1.5
  }
}

sequenceDiagram
    A->>B: Hi
    B-->>A: Hi back

7. Understand the fallback chain¶

Rendering goes Kroki-first. If Kroki is unreachable or returns an error, the pipeline can fall back to:

1. A PlantUML server (controlled by PLANTUML_SERVER / USE_LOCAL_PLANTUML) for PlantUML-family diagrams.
2. Mermaid.ink for diagram_type: mermaid.

The successful response includes a source field telling you which backend produced the image:

flowchart LR
    Client -->|generate_uml| MCP
    MCP --> Kroki
    Kroki -.fail.-> PlantUML[PlantUML server]
    Kroki -.fail.-> MermaidInk[Mermaid.ink]
    Kroki & PlantUML & MermaidInk --> Image[(SVG / PNG)]
    Image --> Client

Possible values: "kroki", "plantuml_server", "mermaid_ink". See Fallback strategy and Configuration for the env knobs that control it.

Next steps¶