@crayon-c4/mcp

An MCP server that lets any AI coding agent create, update and maintain a CRAYON-C4 architecture model — in a .NET, Java, Node, Python or any-language repository — and never produce an invalid file.

It works with Claude Code, Claude Desktop, Cursor, VS Code, Zed, or anything else that speaks the Model Context Protocol.

Install

Nothing to install. Point your MCP client at it:

{
  "mcpServers": {
    "crayon-c4": {
      "command": "npx",
      "args": ["-y", "@crayon-c4/mcp", "."],
      "env": {
        // Optional. Without it you get the free tier, which is the whole local
        // authoring loop — see "Licensing" below.
        "CRAYON_C4_LICENSE_KEY": "crayon-c4.…"
      }
    }
  }
}

The "." is the workspace the server works in. Every path a tool is given is resolved inside it and may not escape it — the caller is an agent relaying a path it inferred from a conversation, and the workspace root is the boundary you consented to.

Requires Node 18+.

The guarantee

Every model this server writes is valid. Not "usually", not "if the agent is careful":

• every edit tool validates the whole model in memory and adopts the change only if it holds, so a rejected edit leaves the session exactly as it was and the agent is told why;
• write_model re-validates at the boundary and refuses to persist anything invalid;
• validation is two passes, because they catch different things — the published JSON Schema (Draft 2020-12) says whether the file is the right shape, and the app's own semantic validator says whether it means anything: a relationship pointing at an element that is not there, a Component parented to a System, a deployment naming a container id that is gone. No schema can express those, and they are what makes an import render empty.

Errors come back as JSON Pointers with the rule behind each one, so an agent can fix and re-call rather than guess.

What it does

Authoring — scaffold a model, create and update elements with C4 containment enforced, maintain the one central relationship list, build diagrams (with subject drawn as the boundary frame), remove things safely with the cascade reported first, and write with a diff preview.

Understanding — a machine-readable capability map, the authoring guide, known-good examples, and explain_c4, which answers what each diagram level is for rather than what shape it has. The commonest failure of a generated model is not that it is invalid; it is that every diagram shows the same thing at a different zoom.

Scanning (licensed) — detect the stack, derive a C4 model from the code, derive a deployment view from Dockerfiles and compose (declaring every source it did not read — Kubernetes, Helm, Terraform, CI), trace behavioral flows, and merge a re-scan into an existing model without ever discarding hand-written curation. The same merge also reconciles the repository's own adr/*.md decision records — the Git-native format the model itself exports to — so editing a decision file (or writing a brand-new one, with no id required) and re-running merge_model is a real two-way channel, not export-only.

Decisions — find and manage the model's architecture decisions (ADRs): list them by status, category or the element they are about (widened to what is inside it or contains it), read one in full, record a new one linked to elements, move it through its lifecycle, supersede it, renumber it (every mention in the project is rewritten) and check for stale links. The rules are the app's own: an accepted decision is a record whose content can no longer be edited — you supersede it — and status only moves forward. write_model keeps adr/*.md in step, including removing the file a renamed or deleted decision used to live in.

Enrichment (licensed) — list every description still missing (derived from the model itself, so a re-run never re-tasks what somebody already wrote) and fill them, refusing to overwrite prose that is already there.

Guided workflows — five prompts (author-c4-model, add-deployment-view, add-flow, tune-config, enrich-descriptions) that are plans, not lectures: each names the tools, the order, and the trap that particular job falls into.

Where preferences come from

Three voices, ordered by how specific they are to the job:

1. the engine default,
2. this repository — .crayon/config.json, section authoring,
3. this session — set_session_settings.

Later wins, per field. A field nobody set stays at the engine default rather than being written as one, so setting language never silently adopts a granularity you did not mention. get_session_settings reports the effective value and where each one came from, because "why did it emit bidirectional edges" needs an answer.

Licensing

Verification is offline: the public key ships in the binary, so a key works on a plane and this tier emits no telemetry at all.

• Free — every resource, both validation passes, and the whole local authoring loop.
• Licensed — repository scanning (scan) and AI enrichment orchestration (enrich).

A key is read from CRAYON_C4_LICENSE_KEY, then .crayon/license in the workspace.

It fails open. No key, an unreadable file, a forged key, an expired key — every one of them gives you a working free-tier session and a sentence explaining why, never a crash and never a dead server. Call license_status (never gated, never an error) to see exactly what this session can do.

Buy a key at https://crayon-c4.com/#pricing.

Hosted

A second entry point, crayon-c4-mcp-http, serves the same tools over Streamable HTTP for teams. It has no filesystem — your repository is on your machine, not ours — so every tool that reads the workspace is refused there and names the local server to run instead. The in-memory authoring loop, the resources and the prompts all work unchanged.

Walkthrough: from a repository to a model you can import

The point of this sequence is the order. An agent that starts writing elements before it can say what the system is produces a technically valid model that says nothing.

1. Understand what you are modelling.

explain_c4                                  → what C4 is for, and each level
explain_c4 { level: "container" }           → the level most models are missing

Then read crayon-c4://capabilities — the machine-readable rules — and crayon-c4://examples/c4-only for the shape.

2. Say how you want it written. (optional)

set_session_settings { descriptionStyle: "concise", language: "nl" }
get_session_settings                        → the effective values AND where each came from

3. Get a first model. Either derive it —

detect_stack                                → is there anything here to scan?
propose_config                              → measure first: which diagrams come out too big
write_config { config: <the proposal>, confirm: true }
scan_repo { depth: "container", adopt: true }

— or author it by hand:

create_model { name: "Acme Shop" }
upsert_nodes { nodes: [ …system and its containers, in one call… ] }
upsert_relationships { relationships: [ …between the DEEPEST elements that talk… ] }
upsert_layer { id: "l-context",    label: "…", diagramType: "context",   subject: null }
upsert_layer { id: "l-containers", label: "…", diagramType: "container", subject: "sys-shop", parent: "l-context" }
upsert_nodes { nodes: [{ id: "sys-shop", zoomLevel: "l-containers" }] }   → drill-in

4. Fill in the prose. (licensed)

list_enrichment_tasks { limit: 10 }         → what is missing, and the file to read it FROM
apply_enrichment { fills: [ … ] }           → refuses to overwrite anything already written

5. Check and write.

validate_model                              → fix every error; read the warnings
write_model                                 → a DIFF, and nothing written
write_model { confirm: true }               → writes the model + its sidecars

6. Later, when the code has moved on.

merge_model                                 → the whole change set, nothing applied
merge_model { apply: true, acceptRemovals: [ … ] }

merge_model never discards curation: descriptions and names a person wrote are kept, a name that changed on both sides is reported as a conflict and left alone, and an element the code no longer has is removed only if you ask for it by id — and never if it was hand-authored in the first place. A decision record in adr/*.md is never removed by it at all — nothing about a decision is code-derived, so a file that disappeared is reported and kept, not offered for removal; and a record past proposed is never overwritten by the file, whatever you resolve, because the model's own accepted/deprecated/superseded immutability rule applies here too.

Finally, import crayon-c4-project.json at https://crayon-c4.com (New project → From file, or Update from code on an existing one) to draw, curate and share it.

Reference

Legend: fs = reads or writes your workspace, so it is refused on the hosted transport.

Tools

Resources

Prompts

Files it writes

Only on write_model { confirm: true }, and only beside the model:

Commit all four. .crayon/license, if you use one, should be in .gitignore.

Licence and privacy

CRAYON-C4 is proprietary; see LICENSE. The bundled open-source dependencies are listed with their notices in THIRD-PARTY-NOTICES.txt.

The server reads only the workspace you point it at, and only when you call a tool that says it does. The offline tier makes no network requests of any kind.

Support: https://crayon-c4.com/support