JGS Archi Bridge is an Eclipse plugin for Archi that embeds an HTTP server speaking the Model Context Protocol inside a running Archi instance. Any MCP-compatible agent (Claude Code, Cline, LM Studio) can then query, search, analyse, and directly change the ArchiMate model you have open, in the same session, on the same screen.
Every write goes through Archi's own CommandStack, so an agent's change is undone with Ctrl+Z exactly like a manual edit. A human-owned approval gate can hold changes for review before they apply. The default bind is loopback only, so nothing leaves your machine.
Most tooling that connects an AI agent to an ArchiMate model works on the file: it parses the exported XML, computes a change, and writes a new file back. JGS Archi Bridge does not do that. It runs a small HTTP server inside the Archi process, so the agent operates on the model you already have open, while you have it open. There is no export step, no re-import, and no second copy to reconcile.
You start the server from Archi's own menu (MCP Server > Start MCP Server) with your model
open. Your GUI stays exactly where it is. The server listens on http://127.0.0.1:18090/mcp by
default and answers over the standard MCP protocol.
Reads (search, traversal, view inspection) run straight off Archi's in-memory model on the server's own
threads. Writes are dispatched onto Archi's SWT UI thread via Display.syncExec() and executed as
commands on Archi's native CommandStack, the same stack a human edit uses.
Because the mutation runs through Archi's real command layer, a new element, a re-routed connection, or a whole composed view shows up on your diagram immediately, correctly styled, exactly as if you had drawn it.
Every agent change is a command on the undo stack. Ctrl+Z reverts it. The agent's own
undo/redo tools are scoped to the agent's changes and refuse to cross a human edit,
so an agent can never silently roll back work you drew by hand.
Concretely: the model is never serialised out and read back to make a change. The trust boundary is a loopback HTTP port, and the edit boundary is Archi's CommandStack. That is why undo, redo, and validation behave identically for agent and human edits.
File-parsing tools (coArchi2-style) compute a change against an exported model and hand you a new file. You then merge or reload, and your undo history is gone. Here the agent's change is a first-class command on Archi's stack: undo it, redo it, or keep editing on top of it without leaving Archi.
Mutations are never stricter nor more forgiving than Archi itself. A relationship the GUI would reject is rejected here, with a structured error citing the relevant ArchiMate 3.2 specification section. The agent cannot coerce the model into a state Archi would not allow.
There is no exported copy drifting out of sync with what is on your screen. The agent reads and writes the live model, so what it sees, what you see, and what gets saved are the same object.
The server carries a full layout and routing pipeline (ELK layered layout, orthogonal connection routing, a layout-quality assessor). The agent does not just create elements: it composes readable diagrams and can measure whether the result is legible before showing it to you.
The approval gate defaults to GATED on a fresh install (fail safe). An agent acting on untrusted input, say a prompt-injected document, cannot apply a destructive change without your explicit approval in Archi. You review a plain-language card and decide.
The server binds to 127.0.0.1 and validates the Origin/Host header,
so a remote host cannot reach it and a browser page cannot drive it. Optional TLS and an opt-in bearer token
are there when you need them, but the default posture is closed.
Grouped by function. Each group is a set of MCP tools the agent calls in natural conversation, plus 14 reference resources (ArchiMate layer and relationship guides, viewpoint recipes, workflow prompts) the agent fetches to model correctly.
Model overview, element and relationship retrieval, multi-hop relationship traversal, view contents with full styling read-back, and reverse where-used lookup.
Example
"What applications support the Customer Portal capability?" The agent searches elements, traverses relationships, and returns the supporting components.
Full-text search across names, documentation, and properties with type, layer, and specialization filters. Discovery-first create tools avoid duplicating an element that already exists.
Example
"Find all Application Services in the model" or "Show me the relationships between the CRM and ERP systems."
Create and update elements, relationships, views, and the model itself, with ArchiMate rule enforcement, duplicate detection, specializations (IS-A subtypes), and folder management.
Example
"Create a new view showing the payment processing flow" builds the elements, wires the relationships, and places them on a fresh diagram.
Place elements, groups, notes, image nodes, and view references onto diagrams; nest containers with an auto-receding backdrop; anchor an object to follow a container as it grows; style every visual.
Example
"Add the fraud engine to this view and connect it to the payment gateway" places and links the visual in one step.
ELK-backed automatic layout, orthogonal connection routing, group arrangement, hub sizing, and density-aware spacing tools that self-terminate honestly rather than looping.
Example
"Auto-layout and route the connections on this view" computes positions and clean orthogonal paths in a single atomic operation.
A layout-quality assessor rates a view across overlap, crossing, terminal, spacing, and hub-port metrics, and reports a coverage map so a done-gate knows what was actually checked.
Example
"Is this diagram readable, and what should I fix?" returns a tiered rating with the specific tool to run for each defect.
Render any view to PNG, JPG, SVG, or PDF, inline or to file, each render stamped with the model's mutation version so a stale image is detectable. Import icons into the model archive.
Example
"Export the landscape view as an SVG" writes a vector render you can drop into a document.
Group mutations into atomic transactions, run compound bulk-mutate commands with
back-references, and undo or redo agent changes as scoped, native command-stack operations.
Example
"Undo the last three changes you made" reverts only the agent's own edits, stopping at any human edit on the stack.
When you turn on Approval Mode, the agent's mutations queue as pending instead of applying. The agent can only observe that it is gated; it cannot approve its own changes. You decide in Archi.
Example
The agent calls list-pending-approvals, sees its changes are held, and tells you to confirm
them in the Pending Approvals dock.
Full tool and resource reference is in the
README. The plugin also ships a
prompt library, including
repo-to-archimate-model.md (also the /repo-to-archi Claude Code slash command), which
reverse-engineers a code repository into a full, evidence-marked ArchiMate 3.2 model.
If you are an enterprise architect or systems engineer who already models in Archi, the appeal of an AI agent is obvious: describe a change, get it drafted. The hesitation is equally obvious: you are handing a language model write access to a model that took real work to build, and one bad batch could corrupt it.
This tool is designed around that hesitation, not around a demo. Three properties make the difference:
Agent edits are commands on Archi's undo stack. If a result is wrong, Ctrl+Z takes it back. You are never one step from an unrecoverable state.
With Approval Mode on, nothing the agent writes touches the model until you approve it from a plain-language card that names exactly what changes, with deletions called out.
The server refuses any mutation Archi itself would refuse. The agent works within the ArchiMate specification, not around it, so the model cannot be driven into an inconsistent state.
The result is a way to move from curiosity to daily use: start read-only, keep the approval gate on, watch what the agent proposes, and open up write access on your own schedule once you trust it. Nothing forces you further than you want to go, and nothing you do is irreversible.
You need Archi 5.7 or later, Java 21 or later, and an MCP-compatible client. The condensed path is below; the README covers every client and every option in full.
Download the latest .archiplugin from
Releases (or the repo's
bin/ directory). In Archi, use Help > Manage Plug-ins > Install New..., or
drop the file into Archi's dropins/ folder. Restart Archi.
Open an ArchiMate model, then choose MCP Server > Start MCP Server from Archi's menu bar.
The default endpoint is http://127.0.0.1:18090/mcp. Port, bind address, TLS, and authentication
live under Window > Preferences > MCP Server.
For Claude Code, one command connects it:
claude mcp add --transport http archi http://127.0.0.1:18090/mcpClaude Desktop needs a proxy (uvx mcp-proxy) because it
does not natively support Streamable HTTP. Cline and other clients point directly at the
Streamable-HTTP endpoint (/mcp), or the SSE endpoint (/sse) for older clients.
With the server running and the client connected, describe what you want: "Give me an overview of this architecture model", "What does the Order Processing component depend on?", or "Create a view showing the payment processing flow and lay it out."
Full docs: Install · Configuration · Usage guide · Tool reference
The threat is not the hostile internet. It is other local processes on your machine, LAN neighbours after one preference change, and a prompt-injected agent, and the mitigations are sized for exactly those.
From SECURITY.md
Because the server exposes mutating and file-touching tools over HTTP, the trust boundary is stated plainly. Three controls are the headline, and all are on with zero configuration:
The default bind address is 127.0.0.1, so the port is not reachable from the network.
Origin/Host validation rejects a browser page trying to drive the tools via
DNS-rebinding. Binding off-loopback is opt-in and warned about.
A fresh install defaults to GATED (fail safe). The agent has no tool to ungate itself or approve its own changes; it can only observe that it is gated. Turning the gate off requires a desktop confirmation in Archi.
Every mutation is undoable through Archi's CommandStack. The agent's undo/redo
stop at, and refuse to cross, any human edit, so the agent cannot silently revert your hand-drawn work.
Optional hardening is yours to enable when the deployment calls for it: TLS with a self-signed or supplied certificate, and an opt-in 256-bit bearer token. Both secrets (the token and the keystore password) are stored in your OS keychain via Equinox secure storage (macOS Keychain, Windows Credential Store), never in cleartext on disk; the server fails closed rather than falling back to plaintext. If you bind off-loopback, securing the surface (firewall, TLS, bearer token) becomes your responsibility, and the preferences page warns you at the moment you cross that line.
Read the full SECURITY.md before binding off-loopback or pointing an agent at untrusted input. It states, control by control, what is protected by default, what is your responsibility as operator, and how to report a vulnerability.
JG Systems Consulting Ltd is an independent systems architecture and MBSE (model-based systems engineering) consultancy. We work inside client organisations on real enterprise-architecture and systems-engineering programmes, in tools like Archi, CATIA Magic, and Sparx Enterprise Architect, not in a research lab. Archi MCP Server exists because we needed it ourselves: a way to let an AI agent work inside a live architecture model without breaking the model, the audit trail, or the architect's trust in either.
That practitioner origin shapes the whole design. The approval gate, the loopback-only default, and routing
every mutation through Archi's own CommandStack instead of a bespoke undo system are not features
added to look responsible for a demo. They are what we require before we let an agent near a client's model, and
what we ship by default here.
The plugin is MIT licensed and open source. It was forked from fanievh/archi-mcp-server, and JG Systems Consulting Ltd has maintained and extended it: the layout and routing engine, the assessment tooling, specialization and view-composition support, and the mutation-safety model are original work from this fork, released under the same licence. Every push runs the full test suite (4,082 tests across 181 classes) on GitHub Actions.
This is one of a family of local-first, agent-friendly tools we build and open-source alongside our consulting work: bridges and skills that bring AI agents to real engineering models, on the architect's own machine, with nothing sent to the cloud. Most are free to use; a few are licensed. See the rest at labs.jgsystemsconsulting.com, or get in touch about an architecture or MBSE engagement at www.jgsystemsconsulting.com.