Skip to main content

Connect an AI agent with the ZenUML MCP server

The ZenUML MCP server lets an AI agent work with ZenUML diagrams in Confluence. Any client that supports the Model Context Protocol, such as Claude Code, Codex, Cursor or VS Code, can find, read, create and update diagrams and pages. You don't need to keep a browser tab open.

The agent signs in with your Atlassian account and acts as you. It can reach only the sites, spaces and pages that your Confluence permissions already allow.

Set it up

1. Open the MCP dialog on a diagram

Open a Confluence page with a ZenUML diagram and hover over the diagram. Its header shows the diagram's actions. Select MCP, the button with the MCP icon next to the code icon (its tooltip says "Connect MCP"):

The diagram header on hover, with the MCP button between the code icon and the More menu

If the diagram is narrow or has a long title, the header has less room:

  • The button shows only the MCP icon, without the "MCP" label.
  • On the narrowest diagrams it moves into the ⋯ (More) menu as Connect MCP.

In fullscreen, the MCP button is always visible in the header, with its label.

The dialog shows the setup command for your site and a ready-made prompt for that diagram.

The Connect MCP button is rolling out gradually, starting with ZenUML Lite. It appears on every diagram type: sequence, Mermaid, PlantUML, Markdown, Graph (draw.io), OpenAPI, AsyncAPI and embedded diagrams. If you don't see it, it hasn't reached your site yet.

2. Add the server to your MCP client (once)

In Claude Code, run the command from the dialog. For ZenUML Lite it is:

claude mcp add --transport http zenuml https://conf-lite.zenuml.com/agent-link/mcp

In claude.ai or the Claude desktop app, add a custom connector with the URL shown in the dialog.

For other MCP clients, add a remote HTTP server named zenuml with the URL shown in the dialog.

3. Sign in with Atlassian

The first time your agent uses the server, your client opens an Atlassian sign-in page. Approve the request to let ZenUML read and write pages and diagrams on your behalf. You only need to do this once. If you don't use the connection for 90 days, Atlassian asks you to sign in again.

4. Ask your agent to review the diagram

Paste the prompt from the dialog into your agent. The prompt identifies the diagram, so the agent can go straight to it. It asks the agent to read the diagram and its page, summarize what the diagram shows, point out anything unclear, inconsistent or missing, and suggest improvements. The agent waits for your go-ahead before it changes anything.

You can also ask in plain language without the dialog, for example "List the ZenUML diagrams on my Architecture page" or "Add a retry when the payment service times out to my Checkout flow diagram".

Reload the Confluence page to see your agent's changes.

See diagrams in the conversation

In clients that support MCP Apps, such as claude.ai and the Claude desktop app, your agent shows the diagram itself instead of only its source. When it reads or creates a diagram, the rendered diagram appears inline in the conversation, so you can check it without opening Confluence. After an update, ask your agent to read the diagram again to see the result.

  • Sequence, Mermaid, PlantUML, Markdown, Graph (draw.io) and OpenAPI diagrams are drawn inline. OpenAPI specs show as a read-only API reference, without "Try it out".
  • AsyncAPI documents show as an outline: the title and version, servers, channels, operations and messages. It's simpler than the AsyncAPI view on the Confluence page.
  • Embedded diagrams aren't drawn. The inline area shows a short message instead of a picture.
  • Clients without MCP Apps support show the diagram's source as text. Everything else works the same.

The preview is read-only. To edit a diagram, ask your agent or open the page in Confluence.

What your agent can do

ToolWhat it does
list_sitesLists the Confluence sites your sign-in can reach.
list_diagramsLists ZenUML diagrams on a site or on one page, most recently changed first.
read_diagramReads a diagram's source and type. Shows the diagram inline in clients that support MCP Apps.
update_diagramReplaces a diagram's source. To see the result drawn, ask your agent to read the diagram again.
create_diagramCreates a sequence, Mermaid, PlantUML, Markdown, Graph, OpenAPI or AsyncAPI diagram and adds it to a page. Shows the result inline in clients that support MCP Apps.
read_pageReads a page's title and body.
create_pageCreates a page under an existing page. Can create it as a draft for you to review.
update_pageReplaces a page's body and, optionally, its title.
get_statusShows who the connection acts as and which ZenUML app each site runs.

Safeguards

  • Every change is a new version. A page edit publishes a new page version, which you can review or restore from page history. A diagram edit saves a new version of the diagram itself, not of the page, so it doesn't appear in page history. Confluence keeps the earlier diagram versions, but there's no button to restore one. To undo a diagram change, ask your agent to put the previous source back.
  • No silent overwrites. If someone edits a page after your agent read it, the update is refused, so the agent doesn't overwrite their work.
  • Broken edits are refused. A diagram change that fails to parse, or a body that looks accidentally cut off, is rejected and the diagram or page stays as it was.
  • Your permissions apply. The agent can't see or change anything you couldn't see or change yourself in Confluence.

Your agent sends diagram and page content to whichever AI model your client uses. Before you connect it to pages with confidential content, check that this is allowed where you work.

The inline preview draws every diagram in your client, PlantUML included. It doesn't send the diagram's source to plantuml.com or any other third party.

Stop using the server

Remove the zenuml server from your MCP client. In Claude Code, run:

claude mcp remove zenuml

To revoke ZenUML's access entirely, remove it from the connected apps in your Atlassian account settings.