The MCP server

Working with agents·5 min read·Edit this page

The diagramming MCP server lets Claude Code — and other MCP-capable agents — read and write your .diagram files directly, in real time. When the agent edits the file, the canvas updates instantly. You can watch the diagram take shape and jump in to adjust at any point.

Unlike cloud-based diagram tools where an agent mutates a remote workspace via API, here the agent co-edits the same source file in your repo. Every change is a text edit on the .diagram file — reviewable, revertible, branchable like any code change.

Add the MCP server to Claude Code

Install the MCP server using the Claude Code CLI. Run this command from your terminal — it registers the server globally for all your Claude Code sessions.

1
Register the MCP server
Run this once. It adds diagramming to your Claude Code MCP configuration.
shell
```
claude mcp add diagramming \
  --transport http \
  --url https://mcp.diagramming.dev/mcp
```

Or: configure manually in claude_mcp_settings.json

If you prefer manual configuration, add the following to your Claude Code MCP settings file:

json

{
  "mcpServers": {
    "diagramming": {
      "transport": "http",
      "url": "https://mcp.diagramming.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_TOKEN"
      }
    }
  }
}

Generate an agent token
Agent tokens authorise Claude Code to access a specific diagram. Generate one from the diagram's Agent tokens panel.
Generate a token in the app
Open any diagram in diagramming, then open the Agent tokens panel from the diagram settings. Choose a permission level (read-only or read & write) and an expiry up to 14 days. This creates a scoped token valid for that diagram. Paste it as YOUR_AGENT_TOKEN above.

Tools the agent gets

Once connected, Claude Code has access to the following MCP tools scoped to the diagram and session you authorised:

read-diagram

Read the current diagram file. Returns the full .diagram text for the active session. The agent calls this to understand the current state before making edits.

write-diagram

Write a new version of the diagram file. Accepts the full .diagram text; the server validates the syntax and propagates the update to all connected canvas clients in real time. Human collaborators see the change appear live.

read-comments

Read comment threads anchored to the diagram. Returns an array of comments with author, body, node anchor, and resolved state. Useful when the agent needs context from previous review discussions.

post-comment

Post a comment to the diagram. Anchors the comment to a specific node ID. Appears in the canvas's comment panel and sends a notification to collaborators.

Token scope & expiry

Token is scoped to a single diagram session

An agent token grants access only to the specific diagram and branch it was generated for. It does not grant access to your GitHub account, other diagrams, or any files outside the session. Tokens expire after 7 days by default (maximum 14 days) — you can revoke one at any time from the Agent tokens panel.

If you open the same diagram on a different branch, you'll need a new token for that branch. This is intentional — it matches the branch-per-token model, so you can give Claude Code access to a feature/refactor branch without touching main.

The canvas shows the agent working

While Claude Code is using write-diagram, an "Agent is editing…" banner appears at the top of the canvas and the agent's violet cursor moves across nodes in real time. You can edit simultaneously — conflicts are merged automatically.

Example prompts to try

Once the MCP server is wired up, here are some prompts to start with in Claude Code:

claude code prompt

# Draft a diagram for this repo
"Read the architecture of this repo and draft an architecture
diagram using the diagramming MCP tool. Keep it to the top-level
services and their connections."

# Add a node
"Add a Redis caching layer between the API and the Postgres
database in the diagram. Use a dashed edge labelled 'read-through'."

# Refactor
"The monolith node in the diagram should be split into three
services: auth-service, billing-service, and notification-service.
Update the diagram and reconnect the edges."

# Explain via comment
"Post a comment on the 'db' node explaining why we chose Postgres
over a document store for this data model."

Open a repo The Claude Code skill