Enables AI agents to author, validate, layout, render, and diff architecture diagrams as code.
Also known as hudsonkit/arc, arc-8a429f, @hudsonkit/arc-mcp
- Stars
- 17
- Tools
- 10
- Downloads, 30 days
- 509
- Latest version
- 0.14.1
- Last commit
- Nov 14, 2026
- License
- MIT
What is Arc MCP?
Arc enables AI agents to author, validate, layout, render, and diff architecture diagrams as code. It exposes 10 tools, such as validate_diagram, diff_diagram, auto_layout.
Summary generated from the project's README
About Arc MCP server
Arc provides a specialized toolchain for AI agents to manage architecture diagrams as code through the Model Context Protocol. It allows agents to author, validate, layout, render, and diff complex diagrams using a structured data format. The server runs locally via stdio using Node.js 22 or newer, making it compatible with clients like Claude Code and Devin without requiring external accounts or API keys.
Developers can use specific tools to transform diagrams into various formats, including SVG, PNG, HTML, and even ASCII box-art for terminal displays. The server supports advanced workflows like live diagramming in the Arc studio and durable architecture reviews. While most operations are local, rendering PNGs requires a local Chrome or Chromium installation, and generating animations requires ffmpeg. The system also enables structural diffing and automatic layout of nodes and connectors to maintain organized visual representations of system designs.
Written from the project's README. Every use case is checked against a quote from it.
How to install Arc MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Arc MCP in Claude Code
$ claude mcp add arc-8a429f -- npx -y @hudsonkit/arc-mcpInstall Arc MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"arc-8a429f": {
"command": "npx",
"args": [
"-y",
"@hudsonkit/arc-mcp"
]
}
}
}Install Arc MCP in VS Code
.vscode/mcp.json
{
"servers": {
"arc-8a429f": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@hudsonkit/arc-mcp"
]
}
}
}Install Arc MCP in VS Code CLI
$ code --add-mcp '{"name":"arc-8a429f","type":"stdio","command":"npx","args":["-y","@hudsonkit/arc-mcp"]}'Install Arc MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"arc-8a429f": {
"command": "npx",
"args": [
"-y",
"@hudsonkit/arc-mcp"
]
}
}
}Install Arc MCP in Codex
$ codex mcp add arc-8a429f -- npx -y @hudsonkit/arc-mcpInstall Arc MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.arc-8a429f] command = "npx" args = ["-y", "@hudsonkit/arc-mcp"]
Install Arc MCP in Gemini CLI
$ gemini mcp add -s user arc-8a429f npx -- -y @hudsonkit/arc-mcpInstall Arc MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"arc-8a429f": {
"command": "npx",
"args": [
"-y",
"@hudsonkit/arc-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @hudsonkit/arc-mcp 0.14.1 in an isolated container with no network and no keys. It answered and listed 10 tools.
Arc MCP tools 10
Read from the server with tools/listvalidate_diagramValidate an ArcDiagramData document. Returns coded diagnostics — consume by `code`, apply one `supportedFixes` entry, re-validate. `ok` is false while any error-severity diagnostic remains.
diff_diagramStructural diff of two Arc diagrams. Returns a DiagramDelta — added/removed/moved/changed nodes, connector adds/removes/changes (keyed by connector id or from→to), connectorStyles and groups deltas, layoutChanged. Feed it to <ArcDiagram data={head} delta={delta} /> for a diff render.
auto_layoutRun Arc auto-layout on a diagram. Pass a full diagram or minimal input (nodeData + connectors + connectorStyles).
render_asciiRender an Arc diagram as monospace ASCII/Unicode box art.
render_svgRender an Arc diagram as deterministic SVG markup using the package export path.
render_pngRender an Arc diagram as a PNG via an installed Chrome/Chromium binary. Returns MCP image content plus render metadata. Set ARC_CHROME if Chrome is not on PATH.
render_animationRender diagram flows as a GIF or MP4 artifact. Uses deterministic frame captures through Chrome plus ffmpeg; requires an `output` path because video payloads are too large for MCP text.
render_htmlRender an Arc diagram as a React component snippet, iframe embed, or standalone HTML page.
diagram_to_typescriptConvert a valid Arc diagram JSON into a TypeScript module that exports ArcDiagramData.
editor_handoffBuild URLs to open a diagram in the Arc studio. Returns a hash-based editor URL and showcase link.
| validate_diagram | Validate an ArcDiagramData document. Returns coded diagnostics — consume by `code`, apply one `supportedFixes` entry, re-validate. `ok` is false while any error-severity diagnostic remains. | |
| diff_diagram | Structural diff of two Arc diagrams. Returns a DiagramDelta — added/removed/moved/changed nodes, connector adds/removes/changes (keyed by connector id or from→to), connectorStyles and groups deltas, layoutChanged. Feed it to <ArcDiagram data={head} delta={delta} /> for a diff render. | |
| auto_layout | Run Arc auto-layout on a diagram. Pass a full diagram or minimal input (nodeData + connectors + connectorStyles). | |
| render_ascii | Render an Arc diagram as monospace ASCII/Unicode box art. | |
| render_svg | Render an Arc diagram as deterministic SVG markup using the package export path. | |
| render_png | Render an Arc diagram as a PNG via an installed Chrome/Chromium binary. Returns MCP image content plus render metadata. Set ARC_CHROME if Chrome is not on PATH. | |
| render_animation | Render diagram flows as a GIF or MP4 artifact. Uses deterministic frame captures through Chrome plus ffmpeg; requires an `output` path because video payloads are too large for MCP text. | |
| render_html | Render an Arc diagram as a React component snippet, iframe embed, or standalone HTML page. | |
| diagram_to_typescript | Convert a valid Arc diagram JSON into a TypeScript module that exports ArcDiagramData. | |
| editor_handoff | Build URLs to open a diagram in the Arc studio. Returns a hash-based editor URL and showcase link. |
Configuration
ARC_MCP_HOST
| Name | Description | |
|---|---|---|
| ARC_MCP_HOST | — |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablehudsonkit/arc is public and reachablegithub.com/hudsonkit/arc ↗Pass
- Package names this repository as its source@hudsonkit/arc-mcp names hudsonkit/arc as sourcenpmjs.com/package/@hudsonkit/arc-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @hudsonkit/arc-mcpnpmjs.com/package/@hudsonkit/arc-mcp/v/0.14.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/hudsonkit/arc ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @hudsonkit/arc-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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
| Tool | What it does |
|---|---|
validate_diagram |
Coded diagnostics for ArcDiagramData — consume by code, apply a supportedFixes entry, re-validate |
auto_layout |
Auto-layout a full diagram or minimal input (nodeData + connectors + connectorStyles) |
diff_diagram |
Structural DiagramDelta — feed to <ArcDiagram data={head} delta={delta} /> for a diff render |
render_svg |
Deterministic SVG export — eleven themes, light/dark; authored flows animate via SMIL or sample at flowTime |
render_png |
PNG raster via a local Chrome/Chromium binary (ARC_CHROME to override, ARC_CHROME=none to disable), sampled at flowTime |
render_animation |
GIF/MP4 flow animation to an output path via Chrome frames + ffmpeg (ARC_FFMPEG to override) |
render_html |
React component snippet, iframe embed, or standalone HTML page |
render_ascii |
Unicode/ASCII box-art rendering for terminals and docs |
diagram_to_typescript |
Emit a typed ArcDiagramData TypeScript module |
editor_handoff |
Build URLs that open the diagram in the Arc studio |
open_live_diagram |
Open a live architecture view and return its stable URL and session ID |
begin_live_diagram_work |
Declare work before starting it, with a summary and canvas, node, or region scope |
update_live_diagram |
Publish a complete validated diagram revision to that view |
finish_live_diagram_work |
Finish the current work ID and leave the view idle for the next task |
end_live_diagram |
Mark the diagram complete and retain the final view |
open_architecture_review |
Save a baseline and open a durable architecture review |
update_architecture_review |
Save findings, evidence, decisions, questions, and summary |
resume_architecture_review |
Resume an interrupted review with its author capability |
revoke_architecture_review_share |
Invalidate the old viewer link and return a new capability |
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":"<returned ID>","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
| URI | Content |
|---|---|
arc://schema/diagram |
Generated draft-07 JSON Schema for ArcDiagramData |
arc://skill/diagrams |
Arc diagram-generation skill for agents |
arc://docs/llm |
Dense LLM briefing |
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
| Variable | Default | Purpose |
|---|---|---|
ARC_MCP_PORT |
5190 |
Port to listen on |
ARC_MCP_HOST |
127.0.0.1 |
Interface to bind; nonloopback binds require ARC_MCP_TOKEN |
ARC_MCP_PUBLIC_URL |
http://<host>:<port> |
Externally reachable origin used in live stream URLs and Host validation; preserve this Host through a reverse proxy |
ARC_MCP_ALLOWED_ORIGINS |
Studio and relay origins | Additional comma-separated browser origins permitted to use /mcp |
ARC_EDITOR_URL |
http://localhost:5188 |
Studio base used by handoffs and live views |
ARC_MCP_TOKEN |
Unset | Agent bearer credential; required outside loopback |
ARC_STUDIO_DIR |
Unset | Production studio build to serve beside MCP |
ARC_REVIEW_DIR |
~/.arc/reviews |
Private durable review storage, outside the studio build |
Arc doesn't run a public MCP endpoint. If you need a hosted one, open an issue at github.com/hudsonkit/arc.
MCP Registry
Arc's registry identity is io.github.hudsonkit/arc. The install metadata lives
in server.json, and the npm package declares the same
mcpName so the registry can verify ownership.
Maintainers can run the Publish to npm GitHub Actions workflow with package
scope mcp for an MCP-only patch release, or all for a coordinated release.
The workflow sets both versions before building, verifies the packed server,
publishes npm, then publishes the registry metadata using GitHub OIDC. A dry run
validates and packs without publishing. GitHub's curated MCP catalog requires
initial onboarding
after publication to the official MCP Registry.
Related packages
@hudsonkit/arc— React renderer, visual studio,arcCLI, ASCII renderer@hudsonkit/arc-viewer— native Mermaid sequence diagrams + Mermaid import@hudsonkit/arc-iso— isometric renderer for vanilla JS and the browser
Studio + docs: hudsonkit.com/arc · Source: github.com/hudsonkit/arc
License
Arc MCP questions
How do I add Arc MCP to Claude Code?
Run claude mcp add arc-8a429f -- npx -y @hudsonkit/arc-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Arc MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Arc MCP provide?
It exposes 10 tools, including validate_diagram, diff_diagram, auto_layout, render_ascii, render_svg.
What are the requirements for setting up the client?
The client requires Node.js 22 or newer. For PNG exports, a local Chrome/Chromium installation is needed, and ffmpeg is required for animation exports.
Does the server require an API key?
No, no account or API key is required for standard setup.