Umlout MCP Server

Let your AI assistant draw on a real whiteboard.

Umlout exposes a hosted Model Context Protocol server, so Claude, Cursor, VS Code Copilot and any other MCP client can build and edit projects in your Umlout workspace — UML class, sequence, activity and state boards, flowcharts, wireframes, agile and planning boards, floor plans, dashboards and cloud architecture drawn with the AWS, Azure and Kubernetes icon sets.

Nothing to install and nothing to run: the server is hosted at https://www.umlout.com/mcp/http (Streamable HTTP). The older SSE address, /mcp/sse, still answers, but an SSE session does not survive a restart of the service, so a client pointed at it fails after every deploy until it is reconnected by hand. Use /mcp/http. You only need an API key.

Quick start

1. Get an API key. Sign in at umlout.com, open Profile → AI clients, pick your client and create a key. The profile page gives the exact text for your client with the key already in it.

2. Add the server to your client.

claude mcp add --transport http umlout https://www.umlout.com/mcp/http --header "Authorization: Bearer YOUR_API_KEY"

More options, including project scope: examples/claude-code.md.

~/.cursor/mcp.json:

{
  "mcpServers": {
    "umlout": {
      "url": "https://www.umlout.com/mcp/http",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code reads a different shape — servers, not mcpServers, and "type": "http" — so use examples/vscode.json in .vscode/mcp.json. It prompts for the key and keeps it in VS Code's secret storage instead of a committed file.

Claude Desktop's config file does not take a remote URL directly, so route it through mcp-remote (needs Node.js). Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "umlout": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://www.umlout.com/mcp/http",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Then quit Claude Desktop completely and reopen it — closing the window is not enough.

Codex keeps the key out of its config and reads it from an environment variable — see examples/codex.md.

Every other client takes a JSON file with an address and a headers object; only the name of the address field differs:

{
  "mcpServers": {
    "umlout": {
      "serverUrl": "https://www.umlout.com/mcp/http",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

No key: give the client https://www.umlout.com/mcp/http. It opens an Umlout page where you sign in and allow it. See docs/authentication.md.

3. Ask for a board:

Create a project "Auth" and draw a UML sequence diagram of the OAuth2 authorization code flow on a board in it.

Verify your setup at any time:

python3 scripts/check_connection.py --api-key YOUR_API_KEY

Related MCP server: fcp-drawio

What it can do

95 tools across twelve areas, plus 4 read-only resources. Full reference with every argument: docs/tools.md and docs/resources.md.

Umlout stores a project, and a board is one view of it. A project holds objects — each with a name, exactly one type, its own properties and a description — and the relations between them. A figure on a board is one drawing of an object, so the same object can be drawn on five boards and is still one object; a line on a board is one drawing of a relation.

The figure vocabulary covers 205 figures — basic geometry, UML (class, use case, state, activity, sequence, component, deployment, timing), flowchart, charts and dashboard figures, agile and retrospective cards, plans with stages and tasks, floor plans, and a full wireframe kit — plus the AWS, Azure and Kubernetes icon libraries.

Things worth asking for

• "Turn this OpenAPI spec into a component diagram."

• "Sketch the mobile onboarding flow as wireframes — three screens."

• "Read the board 'Checkout' and tell me which states have no outgoing transitions."

• "Build a project from these requirements: orders, invoices, customers — one type per noun, with their fields — and draw a class board of it."

• "Add a status field to every Task and count the done ones on each Stage."

Authentication and limits

Every request carries your key in Authorization: Bearer <key> (or X-API-Key), or an OAuth token for a client that signs in through the browser. Both are scoped to your account — the assistant sees exactly the projects you can see, with the role you have in each, and nothing else.

Details, key rotation and revocation: docs/authentication.md. Something not working? docs/troubleshooting.md.

About this repository

This repo is the public home of the Umlout MCP connector: documentation, client configs, the registry manifest (server.json) and a connection checker. The server itself is a hosted service — there is no local installation, so there is no server source here.

Issues and questions about the MCP integration are welcome in Issues.

License

MIT — documentation and examples.