Integration · Model Context ProtocolBeta

Use arch-lab from your AI agent

arch-lab runs an MCP server, so Claude Code, Claude Desktop, Cursor and anything else speaking the protocol can read, write and check .alab models. It is hosted — there is nothing to install and no key to configure.

Beta

This integration is in beta. The endpoint URL and the .alab format itself are stable — the format's round-trip guarantees are proven on every build — but tool names, arguments and the wording of responses may still change, and there is no protocol-level versioning to smooth that over yet. Pin nothing to the exact text of a response, and expect to re-read this page after an upgrade.

endpoint

https://arch-lab.dev/api/mcp

What this is for

Your agent can already read and write files — that is the point of a text format, and you should let it edit .alab directly. This server exists for the two things it cannot do on its own: know the grammar exactly and get the real parser's verdict. It is a compiler and a reference, not a filesystem.

Connect

One transport, Streamable HTTP, at the URL above. Open your client — each entry is the complete setup:

Claude Code

One command, once. --scope user installs it for every project on your machine; use --scope project to commit it to a repo instead, or drop the flag to keep it to the current directory.

bash

claude mcp add --transport http arch-lab --scope user https://arch-lab.dev/api/mcp

Claude Desktop

Settings → Connectors → Add custom connector, then paste the URL. Or edit claude_desktop_config.json directly:

json

{
  "mcpServers": {
    "arch-lab": {
      "type": "http",
      "url": "https://arch-lab.dev/api/mcp"
    }
  }
}

Gemini CLI

One command, or add it to ~/.gemini/settings.json by hand under mcpServers with the httpUrl key (url means SSE there, which this server does not speak).

bash

gemini mcp add --transport http arch-lab https://arch-lab.dev/api/mcp

Codex CLI

Add to ~/.codex/config.toml. There is no CLI shortcut for HTTP servers, and no auth key is needed — this server does not authenticate.

toml

[mcp_servers.arch-lab]
url = "https://arch-lab.dev/api/mcp"

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json to get it everywhere.

json

{
  "mcpServers": {
    "arch-lab": {
      "url": "https://arch-lab.dev/api/mcp"
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your workspace, or your user mcp.json to get it everywhere.

json

{
  "servers": {
    "arch-lab": {
      "type": "http",
      "url": "https://arch-lab.dev/api/mcp"
    }
  }
}

Anything else

Any client speaking MCP over Streamable HTTP. There is no authentication and no state — every call is a pure function of its arguments.

text

https://arch-lab.dev/api/mcp

No server? Use the skill

Connecting a server is not the only way to get this. Most of what the MCP server offers an agent is knowledge — the grammar, in exact detail — and knowledge travels fine as a file. If you would rather not add a connector, drop the skill into your project instead:

bash

npx degit raksitnongbua/arch-lab/skills/alab .claude/skills/alab

That writes .claude/skills/alab/SKILL.md — one markdown file, generated from the same syntax reference this server hands out and verified against the real parser on every build. Nothing runs, nothing connects, and it is a normal file you can read and diff.

What you give up

The grammar, but not the verdict. A file in your project cannot tell you whether the model you just wrote actually parses — for that you need validate_model, which means the server, or the validator on this site. The two are not exclusive: plenty of people want the skill for everyday writing and the server for the check at the end.

What it can do

10 tools, all read-only — nothing here mutates anything, on your machine or ours. Grouped by job:

Check and format C4 models

The core loop: get the real parser's verdict on what your agent wrote, then commit canonical bytes that diff cleanly.

validate_model

Validate a model

Check whether model text is valid, and if not, exactly where it breaks. Runs the real arch-lab parser and reports the line, column and offending source line, so a failure can be fixed directly. On success, reports what the model contains (diagrams, levels, counts) rather than echoing it back, plus any C4 review notes — missing technologies, unlabelled or vague relationships, bidirectional lines — which do not affect validity but are what a reviewer will raise. Use this after writing or editing any .alab file: it is the fastest way to confirm the result is both loadable and worth reviewing.

source*: The model text: .alab, arch-lab JSON, or Mermaid C4 (max 256,000 characters).
format: Force a reading: "alab", "json" or "mermaid". Defaults to "auto", which reads the first meaningful line to decide.

format_model

Format a model canonically

Rewrite a model in its own format's canonical form — the exact bytes arch-lab itself would write, so diffs stay minimal and reviewable. Reports when the input was already canonical, so a no-op write can be skipped. Refuses Mermaid, which has no canonical form here.

source*: The model text: .alab, arch-lab JSON, or Mermaid C4 (max 256,000 characters).
format: Force a reading: "alab", "json" or "mermaid". Defaults to "auto", which reads the first meaningful line to decide.

Sequence diagrams

The same check-and-format loop, for message flows over time rather than C4 structure — including the `desc` continuation that keeps a message's endpoint and payload off the arrow.

validate_sequence

Validate a sequence diagram

Check whether SEQUENCE diagram text is valid, and if not, exactly where it breaks. Reads `.alab` sequence documents (first line `archlab 1.0 sequence`) and pasted Mermaid `sequenceDiagram` code, reporting the line, column and offending source line on failure. On success it summarises what the flow contains — participants, messages split by kind, self-messages, how many messages carry a `desc` detail, fragments and their nesting depth, notes, and a FIT report — the rendered pixel size plus any labels too wide for their own arrow, which is the one defect a parse cannot see and a caller cannot look at — rather than echoing the document back. Use this for message flows over time; use `validate_model` for C4 structure diagrams. Passing a C4 document here says so and points you at the right tool.

source*: The sequence diagram text: `.alab` sequence (first line `archlab 1.0 sequence`) or Mermaid `sequenceDiagram` code (max 256,000 characters). The format is detected from the first meaningful line.

format_sequence

Format a sequence diagram canonically

Rewrite sequence text as canonical `.alab` sequence — the exact bytes arch-lab would write, so diffs stay minimal. Also the way to turn a pasted Mermaid `sequenceDiagram` into an `.alab` sequence document, which is a one-way lossy import: the response names what was dropped. Worth a call after writing a message `desc`, which is a JSON string and therefore the one place hand-escaping goes wrong: this reports the bad escape with a line and column, and returns the canonical single-line form when it is right.

source*: The sequence diagram text: `.alab` sequence (first line `archlab 1.0 sequence`) or Mermaid `sequenceDiagram` code (max 256,000 characters). The format is detected from the first meaningful line.

Convert and inspect

Move a model between formats, or read its shape without paying for its full text.

convert_model

Convert between formats

Convert a C4 model to .alab, arch-lab JSON, or Mermaid C4. .alab and JSON are lossless in both directions. Mermaid is a one-way, lossy export of a SINGLE diagram (geometry, tags, icons, drill-down links and traceability are dropped) — good for embedding a picture in a README, never as a source of truth. C4 models only: a sequence document has no Mermaid export here (Mermaid sequenceDiagram is import-only, via format_sequence) — sequence documents travel as .alab text.

source*: The model text: .alab, arch-lab JSON, or Mermaid C4 (max 256,000 characters).
format: Force a reading: "alab", "json" or "mermaid". Defaults to "auto", which reads the first meaningful line to decide.
to*: Target format: "alab", "json" or "mermaid".
diagram_id: Which diagram to emit, for to="mermaid" only. Defaults to the model's root diagram.

describe_model

Describe a model's structure

Read the shape of a model without paying for its full text: metadata, totals, and the drill-down hierarchy of diagrams. Use this to orient in an unfamiliar model, or to find which diagram a change belongs in, before fetching or editing anything.

source*: The model text: .alab, arch-lab JSON, or Mermaid C4 (max 256,000 characters).
format: Force a reading: "alab", "json" or "mermaid". Defaults to "auto", which reads the first meaningful line to decide.
include_contents: Also list every boundary, node and edge of every diagram, in .alab form. Defaults to false, which returns the hierarchy only.

Learn the format

The grammar and real examples — read these before writing .alab, not after the first failure.

get_syntax_reference

Get the .alab syntax reference

The .alab grammar, generated from examples that are verified against the real parser on every build. Read this BEFORE writing .alab by hand — the format has significant indentation and order-free attributes that are easy to guess wrong. Also available as the resource archlab://syntax.

section: One of: overview, example, layout, header, diagrams, frames, nodes, edges, unknown-fields, sequence, errors. Omit for the whole reference.

list_example_models

List example models

List the complete, real C4 models arch-lab ships, with their sizes. Use one as a pattern for idiomatic structure rather than inventing a shape.

No arguments.

get_example_model

Get an example model

Fetch one bundled example model in full, as .alab or arch-lab JSON.

id*: The example's id, from list_example_models (e.g. "shopflow").
format: Either "alab" (default) or "json".

Show a human

Turn a finished C4 model or sequence flow into a link that opens the diagram in the viewer.

create_share_link

Create a share link

Turn a C4 model OR a sequence diagram into a URL that opens it in the arch-lab viewer, so a human can see the diagram — C4 models open the two-pane viewer, sequence documents the sequence playground. The document is encoded into the URL fragment, which browsers never send to a server — nothing is uploaded or stored. Refuses documents too large to fit a link that would survive being pasted into chat or mail. Can optionally expire after a number of days. The format argument applies to the C4 readings; a sequence document is detected from its first line.

source*: The document text (max 256,000 characters). C4 models: .alab, arch-lab JSON, or Mermaid C4. Sequence diagrams: `.alab` sequence (first line `archlab 1.0 sequence`) or Mermaid `sequenceDiagram`. The kind is detected from the first meaningful line.
format: Force a reading: "alab", "json" or "mermaid". Defaults to "auto", which reads the first meaningful line to decide.
diagram_id: Open the link at this diagram (C4 models only — a sequence document is a single flow with no diagrams). Defaults to the root diagram.
ttl_days: Stop the link working after this many days (1-400). Omit for a link that never expires. The expiry is signed so it cannot be edited in the URL, but it is not access control — anyone holding the link can read the model until it lapses.

Resources & prompts

Clients that prefer to pin reference material rather than call a tool for it can read the grammar as a resource:

archlab://syntax
The complete .alab grammar as Markdown, every example verified against the real parser. Pin this when authoring models.

And one prompt, for when you want the whole authoring procedure rather than a single call:

author_c4_model
A working procedure for producing a valid .alab model of a system: read the grammar, draft the levels, validate, then share.
Arguments: system, levels (optional)

A good workflow

The order that avoids rework, whether you drive it yourself or use the author_c4_model prompt:

get_syntax_reference first. .alab has significant indentation and order-free attributes; writing it from memory produces plausible, invalid files.
get_example_model to see idiomatic structure at a real scale before inventing one.
Write the file with your own editing tools. Omit geometry — the defaults are deterministic and lossless.
validate_model until it passes. Every failure comes back with a line, a column and the offending source line.
format_model so the committed file is canonical and diffs cleanly, then create_share_link so a human can actually look at the diagram.

Privacy & limits

Nothing is stored. Every tool is a pure function of the text you send it. There is no database, no account, and no model history — send a model, get an answer, nothing is kept.
Share links do not upload your model. The model is compressed into the URL fragment (after #), which browsers never transmit to a server. Opening one renders entirely in the recipient's browser.
No authentication. The endpoint holds no secrets and reads nothing but its arguments, so there is no key to manage. Do not send a model you would not paste into a public form.
256,000-character ceiling on any single model, which is several times larger than any model anyone has authored. Past it, split the model with childRef.
Mermaid is one-way. Importing Mermaid C4 works; exporting to it drops geometry, tags, icons, drill-down links and traceability. Sequence documents import from Mermaid sequenceDiagram the same one-way — there is no Mermaid export for them at all. Keep .alab or .archlab.json as the source of truth.

The grammar itself is documented at /syntax, and you can check a model by hand at /validate — the same checker this server calls.