# Connect coding agents with the ArcSync MCP server

> Give Claude Code, Cursor, GitHub Copilot and other MCP clients the architecture graph
> ArcSync parsed from your infrastructure-as-code, so they read your real architecture
> instead of guessing it.

Package: `arcsync-mcp` (npm) · stdio transport · Node 22+.
HTML version of this page: https://arcsync.dev/docs/mcp

## What it gives an agent

ArcSync parses Terraform, AWS CDK, CloudFormation, Pulumi, Azure ARM and Serverless Framework
projects into a graph of resources and the relationships between them. The MCP server exposes
that graph through seven tools:

| Tool | What it does |
|------|--------------|
| `list_diagrams` | Lists the diagrams in your workspace; an optional `query` filters by repository, branch or path. |
| `get_diagram` | Returns one diagram as a Mermaid flowchart (or as JSON lists) with a link to the interactive canvas. |
| `describe_resource` | Describes one resource: its type, IaC attributes, and every relationship in and out. |
| `get_delta` | Shows what a pull request changes compared with its base branch, or what a re-parse changed. |
| `list_versions` | Lists a diagram's saved versions (Pro). |
| `start_parse` | Parses a GitHub repository into a new diagram. Uses one parse from your monthly quota. |
| `get_parse_status` | Reports the progress of a parse started with `start_parse`. |

Every tool except `start_parse` is read-only.

## 1. Create an MCP credential

1. Sign in at https://arcsync.dev and open **Settings → GitHub Action credentials**.
2. Enter a label (for example, the machine or agent it is for) and click **Create MCP credential**.
3. Copy the **Client ID** and **Client Secret**. The secret is shown once.

An MCP credential reads your diagrams and starts parses, as you, in your current workspace.
It cannot delete, edit, share, comment, upload, or touch billing. An Action credential is a
separate kind, which only uploads from CI, so it will not work here.

## 2. Store the secret in your shell

```bash
export ARCSYNC_CLIENT_SECRET='arcsec_…'
```

Put it in your shell profile or secret manager, never in a file you commit.

## 3. Add the server to your client

### Claude Code

Add to `.mcp.json` at the repository root (safe to commit, since the secret is expanded from your shell):

```json
{
  "mcpServers": {
    "arcsync": {
      "command": "npx",
      "args": ["-y", "arcsync-mcp"],
      "env": {
        "ARCSYNC_CLIENT_ID": "arc_…",
        "ARCSYNC_CLIENT_SECRET": "${ARCSYNC_CLIENT_SECRET}"
      }
    }
  }
}
```

Or, for your user only: `claude mcp add arcsync -e ARCSYNC_CLIENT_ID=arc_… -e ARCSYNC_CLIENT_SECRET="$ARCSYNC_CLIENT_SECRET" -- npx -y arcsync-mcp`.

### Cursor

Add the same `mcpServers` entry to `.cursor/mcp.json`.

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "arcsync": {
      "command": "npx",
      "args": ["-y", "arcsync-mcp"],
      "env": {
        "ARCSYNC_CLIENT_ID": "arc_…",
        "ARCSYNC_CLIENT_SECRET": "${env:ARCSYNC_CLIENT_SECRET}"
      }
    }
  }
}
```

## 4. Teach the agent when to use it

The server sends the agent short usage instructions when it connects. For Claude Code you can
also add the agent skill, which says when to call each tool:

```bash
mkdir -p .claude/skills/arcsync-mcp
curl -fsSL https://arcsync.dev/docs/mcp-skill.md -o .claude/skills/arcsync-mcp/SKILL.md
```

Then ask, for example, "What does this PR change in our infrastructure?" or "What can the orders
Lambda reach?"

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ARCSYNC_CLIENT_ID` | yes | | The MCP credential's client ID (`arc_…`). |
| `ARCSYNC_CLIENT_SECRET` | yes | | The MCP credential's secret (`arcsec_…`). |
| `ARCSYNC_ORG` | no | your current workspace | Workspace (org) id to act in, when you belong to more than one. |
| `ARCSYNC_API_URL` | no | `https://api.arcsync.dev` | API base URL; must be https. |
| `ARCSYNC_APP_URL` | no | `https://arcsync.dev` | Base for canvas links. |

## Plans and quotas

The server works on every plan. `start_parse` spends a parse from the same monthly quota as
the web app; CDK and Pulumi projects also spend a server-side synth. Version history
(`list_versions`, `get_delta` with a version) and the per-resource pull-request delta are Pro
features. On Free, `get_delta` returns counts only.

## Troubleshooting

- **"ArcSync rejected ARCSYNC_CLIENT_ID / ARCSYNC_CLIENT_SECRET"**: the credential was revoked or
  mistyped. Create a new MCP credential.
- **"Check that it was created as an MCP credential"**: the credential is an Action credential.
  Create an MCP credential instead.
- **A private repository's diagram is not found**: diagrams belong to a workspace. Set
  `ARCSYNC_ORG`, or switch your current workspace in the web app.
- **`start_parse` fails on a private repository**: install the ArcSync GitHub App on it from
  Settings first.

## See also

- GitHub Action setup: https://arcsync.dev/docs/github-action
- Agent overview: https://arcsync.dev/llms.txt