Arc

@hudsonkit/arc-mcp

MCP server for architecture diagrams as code.

Gives AI agents the full Arc toolchain over the Model Context Protocol — author, validate, lay out, render, and diff architecture diagrams from any MCP client.

Run it

No install needed — the server runs over stdio:

npx -y @hudsonkit/arc-mcp

or: bunx @hudsonkit/arc-mcp

Client setup

Requires Node.js 22 or newer. No account, API key, or environment configuration is required. PNG export needs a local Chrome/Chromium installation; animation export also needs ffmpeg.

Claude Code:

claude mcp add --scope project arc -- npx -y @hudsonkit/arc-mcp

Devin:

devin mcp add arc -- npx -y @hudsonkit/arc-mcp

Any MCP client (JSON config):

{

"mcpServers": { "arc": { "command": "npx", "args": ["-y", "@hudsonkit/arc-mcp"] } } }

Tools

Live architecture

Start the Arc studio with bun run dev, then call open_live_diagram with { diagram, title?, agent?: { harness, name? } }. Open the returned liveUrl once. The view starts idle. Before doing diagram work, call begin_live_diagram_work with { sessionId, summary, scope? } and retain its workId. Publish complete revisions with update_live_diagram({ sessionId, diagram, message? }); keep node IDs stable so the viewer can follow each move. In your cleanup/finally path, call finish_live_diagram_work({ sessionId, workId, message? }) when the declared work ends. This leaves the same view idle and reusable. Use end_live_diagram with { sessionId, message? } only when the entire diagram session is complete.

Scope defaults to { type: "canvas" }. Use { type: "nodes", nodeIds: ["api"] } for existing boxes, or { type: "region", x: 400, y: 80, width: 200, height: 160 } for the area where new boxes will appear. A scope accepts 1–200 unique existing node IDs, each at most 200 characters. Region coordinates must be finite and within ±100000; width and height must be positive and at most 100000. Summaries are trimmed, 1–500 characters, and cannot contain control characters. Concurrent begin calls and stale finish IDs are rejected without replacing active work.

The live view belongs to the Hudson Kit Arc studio. ARC_EDITOR_URL selects the studio base URL; open_live_diagram also accepts baseUrl for an individual view, including a deployment prefix such as /arc. The MCP client name/version comes from its initialize handshake. The displayed connection ID is generated by the server; it does not claim to be the client's conversation ID.

The optional agent object declares a harness label and, if useful, an agent name for this view. For example, agent: { harness: "Codex", name: "Reviewer" } adds actor.harness and actor.displayName. These are caller-declared labels, not verified identities. They never replace the actual MCP actor.name, actor.version, or connection actor.id, and do not carry over to other views. Both labels are trimmed, limited to 1–80 characters, and reject control characters.

The local scripts/liveDiagram.control.ts driver accepts ARC_AGENT_HARNESS and optional ARC_AGENT_NAME to send these labels. Neither has a default; ARC_AGENT_NAME requires ARC_AGENT_HARNESS. The driver accepts JSON lines such as {"type":"begin","summary":"Inspect API","scope":{"type":"nodes","nodeIds":["api"]}}, then {"type":"finish","workId":" ","message":"API checked"}. Its status command reports local session metadata. quit closes the relay; it does not claim that unfinished work succeeded.

In stdio mode the first live view starts a loopback HTTP relay on a free port. Keep the MCP process running and open the view on the same computer. The browser may request local-network or loopback-network access when a hosted HTTPS studio connects to that relay. Allow that permission for the studio. Loopback addresses are treated specially by browser mixed-content rules; arbitrary HTTP LAN or remote relay URLs do not get the same guarantee. Browser support, enterprise policy, and the studio's CSP can still prevent the connection. An all-local studio (bun run dev, ARC_EDITOR_URL=http://localhost:5188) avoids the public website-to-loopback permission boundary. For a remote relay used from an HTTPS studio, serve the relay over HTTPS. See the Local Network Access specification and Chrome's permission guidance. HTTP mode serves the stream beside /mcp, so a configured remote relay can be used from another computer. The URL fragment carries a read capability for one diagram; anyone given the full URL can read it. Only its owning MCP connection can update it. Browser requests must come from that view's configured studio origin. The HTTP server enforces ARC_MCP_TOKEN on every MCP request when set, and requires it when binding outside loopback.

Each stream sends the latest full snapshot immediately, including after a reconnect. Invalid updates preserve the previous state. Only explicit work is working; edits outside a declared work item stay idle. Valid updates during work preserve its scope and renew a five-minute lease. Finishing marks the work complete and the session idle. Disconnect or lease expiry marks work interrupted; ending the entire session completes any active work. A later standalone edit clears previous work metadata. These calls describe declared diagram work, not unobserved harness thinking. Unfinished diagrams remain available while their owning MCP connection stays open. Completed diagrams expire one hour after completion; unfinished diagrams expire one hour after their owner disconnects. Stopping the MCP process discards ordinary in-memory live sessions. Save/export a diagram from the studio when it needs to outlive that process.

Live tools require a matching MCP build and studio build. During development, build this checkout with bun run build:mcp and configure the client to run node /absolute/path/to/arc/packages/mcp/dist/arc-mcp.mjs; run its studio with bun run dev. Listing a tool here does not mean an older published package or the currently deployed Hudson Kit website already includes it.

Saved architecture reviews (private preview)

The private preview adds a durable review to the same Hudson Kit canvas. Follow the private preview setup to build matching studio and MCP artifacts and serve them from one private address.

Open with open_architecture_review({diagram,title,question,repository?,agent?}). Repository metadata is {name,url?,revision?}. The result includes a private author resumeToken as well as the normal sessionId and read-only viewer URL. Use the existing begin/update/finish/end tools for declared work and diagrams. Save evidence through update_architecture_review with summary, findings, decisions, and openQuestions; omitted fields stay unchanged, and supplied arrays replace the full previous list.

Findings are {id,title,detail,severity,nodeIds?,sources}, with severity info|low|medium|high. Sources are {path,line?,revision?,url?}. The studio shows those references alongside the canvas, and its Save review action downloads {schemaVersion:1,baseline,snapshot,revisions} without secrets. Source claims are author-supplied evidence, not verified by Arc itself.

Reviews persist before publishing each revision. Keep ARC_REVIEW_DIR and the private server address stable to reopen the same saved viewer link after a restart. Use resume_architecture_review({sessionId,resumeToken,agent?}) after losing the author connection. Optional agent: {harness,name?} supplies caller-declared display labels alongside the new connection's actual MCP identity. Omit it to use only that connection identity. It cannot displace a live author. Completed reviews stay read-only and keep their final author and history unchanged. revoke_architecture_review_share({sessionId}) invalidates the old viewer capability. Saved reviews are not removed by the ordinary live view's one-hour expiry.

For a terminal author, scripts/review.control.ts keeps one HTTP MCP connection open and accepts JSON lines of {id?,name,arguments}. Set ARC_MCP_URL and, if configured, ARC_MCP_TOKEN in its environment. EOF disconnects the author; finish/end calls must be explicit. Keep its output private because opening a review returns author and viewer capabilities.

Resources

Self-hosting over HTTP

The published bin runs over stdio, which is all a local client needs. To serve Arc to clients on other machines, run the Streamable HTTP server from a checkout of the repo:

git clone https://github.com/hudsonkit/arc && cd arc

bun install ARC_MCP_HOST=127.0.0.1 ARC_MCP_PORT=5190 bun run mcp:http

MCP endpoint: http://127.0.0.1:5190/mcp · health: /health

| ARC_MCP_ALLOWED_ORIGINS | Studio and relay or