@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.

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

| Tool | Needs | fs | What it does | |---|---|---|---| | validate_model | free | | Check a model — schema and semantics — inline or by path | | create_model | free | | Scaffold a new, valid model in the session | | read_model | free | fs | Open a model and summarise it (counts, diagrams, what is wrong) | | upsert_nodes | free | | Create or update elements, containment enforced | | upsert_relationships | free | | Create or update the central relationship list | | upsert_layer | free | | Create or update a diagram: its elements, subject, parent, line style | | remove_elements | free | | Safe delete, with the cascade reported first (dryRun) | | set_layout | free | | Pin element positions on one diagram | | write_model | free | fs | Validate → preview a diff → write on confirm | | license_status | free | | Tier, capabilities, and — when unlicensed — exactly why | | explain_c4 | free | | What each diagram level is FOR; six topics in depth | | get_session_settings | free | | The effective settings and which voice decided each | | set_session_settings | free | | This session's preferences, merged per field | | read_config | free | fs | Read and validate .crayon/config.json | | write_config | free | fs | Merge and write it, refusing anything the schema rejects | | detect_stack | scan | fs | Next.js / React / .NET / Java, plus deployment evidence | | scan_repo | scan | fs | Derive a C4 model from the code | | extract_deployment | scan | fs | Dockerfiles + compose → a deployment canvas, declaring what it did not read | | extract_flows | scan | fs | Trace F4 flows from the configured entry points | | merge_model | scan | fs | Fold a fresh scan in without discarding curation | | propose_config | scan | fs | Measure, propose, re-measure | | list_enrichment_tasks | enrich | | Every description still missing, with its source file | | apply_enrichment | enrich | | Write them, never overwriting what is there |

Resources

| URI | What it is | |---|---| | crayon-c4://capabilities | Read this first. Element types and what each is FOR, containment rules, what subject means per level, relationship semantics, the full DC-* constraint catalogue | | crayon-c4://guide/authoring | The prose guide, including the deployment and behavioral slice contracts | | crayon-c4://schema/model | The published model JSON Schema (Draft 2020-12) | | crayon-c4://schema/config | The .crayon/config.json schema | | crayon-c4://schema/decisions | The decisions (ADR) schema | | crayon-c4://examples/c4-only | The smallest complete model | | crayon-c4://examples/full-stack | All three slices, showing the cross-links | | crayon-c4://model/current | The model this session is editing, including unwritten edits | | crayon-c4://config/current | This repository's config as it is on disk | | crayon-c4://license | This session's tier and capabilities |

Prompts

| Prompt | Arguments | What it walks you through | |---|---|---| | author-c4-model | system, depth | Understand the system, then build it bottom-up so the levels agree | | add-deployment-view | environments | Where the containers actually run, linked back to them | | add-flow | flow | What happens during one interaction, across the elements that perform it | | tune-config | — | Make the generated diagrams readable — measure before changing anything | | enrich-descriptions | — | Write what a scan could not infer, without rewriting what a person did |

Files it writes

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

| File | Why it matters | |---|---| | crayon-c4-project.json | The model. Pretty-printed with a trailing newline, so a re-write is a clean Git diff | | crayon-c4-provenance.json | What the last scan derived. It is what lets a later re-run tell a name a person wrote from the one the code last had — without it, a merge quietly takes the code's names back | | crayon-c4-enrichment.json | The source file each missing description should be derived from | | adr/*.md | One file per decision, only written when the model carries any. The same format merge_model reads back — this is what makes editing one directly, or writing a brand-new one, a real two-way channel |

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