arcsync-mcp

An MCP server that gives coding agents (Claude Code, Cursor, GitHub Copilot and other MCP clients) the architecture graph ArcSync parsed from your infrastructure-as-code: Terraform, AWS CDK, CloudFormation, Pulumi, Azure ARM and Serverless Framework.

Tools: list_diagrams, get_diagram (Mermaid or JSON, plus a canvas link), describe_resource, get_delta, list_versions, start_parse, get_parse_status. For diagrams the agent writes itself: validate_diagram (local check), push_diagram (store it and get canvas and Notion embed links), get_diagram_source, list_icons.

Setup

Add to .mcp.json (no credential in it, so it is safe to commit):

{
  "mcpServers": {
    "arcsync": {
      "command": "npx",
      "args": ["-y", "arcsync-mcp"]
    }
  }
}

Claude Desktop

Download arcsync-mcp-<version>.mcpb from the latest release and open it: Claude Desktop installs the extension, with no config file to edit. Leave the two credential fields empty to connect in the browser (below), or fill in both with an MCP credential from Settings.

Without Node.js

Each release also ships a standalone binary. On macOS or Linux, Homebrew installs it (on Intel Macs, Homebrew installs the npm package on its own Node.js instead):

brew install vanlandinghamlabs/tap/arcsync-mcp

On Windows, or without Homebrew, download the archive for your platform from Releases and check it with gh attestation verify <archive> -R VanLandinghamLabs/arcsync-mcp. Then use "command": "arcsync-mcp" with no args, and arcsync-mcp login / logout in place of the npx forms below.

The server is listed in the MCP Registry as io.github.VanLandinghamLabs/arcsync-mcp.

Connect

The first tool call that reaches ArcSync returns a link to https://arcsync.dev/settings/mcp/connect. validate_diagram and list_icons work without connecting. Open it, sign in, and click Connect: ArcSync mints an MCP credential and hands it to the server over 127.0.0.1, which saves it to ~/.config/arcsync/mcp-credential.json (mode 0600) and uses it from the next call. From a terminal, npx -y arcsync-mcp login does the same; npx -y arcsync-mcp logout deletes the saved file.

For CI or a shared machine, create an MCP credential at https://arcsync.dev/settings instead and pass ARCSYNC_CLIENT_ID and ARCSYNC_CLIENT_SECRET in the server's environment; they take precedence over a saved credential.

Two agent skills ship in skills/: arcsync-mcp tells an agent when to call each graph tool, and arcsync-diagrams teaches it to write, validate and push its own diagrams. Install both for Claude Code, Codex, Cursor and the other agents the skills CLI supports:

npx skills add VanLandinghamLabs/arcsync-mcp

The skills do not install the server; add it as above.

Full guide: https://arcsync.dev/docs/mcp

Source and development

This repository is mirrored from the ArcSync monorepo on each release, together with the ArcSync core modules the server uses (vendor/core/). Releases are published to npm from here with provenance, so npm view arcsync-mcp --json links each version to the commit and workflow run that built it. Issues and pull requests are welcome; accepted changes are ported to the monorepo and ship in the next release.

npm ci
npm test
npm run build            # dist/index.js, one self-contained file
npm run eval:diagrams    # arcsync-diagrams skill evals; after build, costs model calls

License

MIT