Archi MCP Server

An Eclipse PDE plugin for Archi that exposes ArchiMate models through the Model Context Protocol (MCP), enabling LLMs to query, analyse, and modify enterprise architecture models through natural language.

What It Does

Archi MCP Server embeds an HTTP server inside Archi that speaks MCP. Once running, any MCP-compatible LLM client (Claude, Cline, LM Studio, etc.) can connect and interact with the currently open ArchiMate model — asking questions, searching elements, traversing relationships, composing view diagrams, and even creating or modifying model content.

The server provides 69 MCP tools across querying, searching, creating, layout, routing, assessment, batch operations, images, specializations, and more — plus 14 MCP resources with ArchiMate reference material, workflow guides, and a viewpoint recipe library for LLMs.

Example conversation:

You: "What applications support the Customer Portal capability?"

LLM: Searches elements, traverses relationships, and returns: "7 applications support Customer Portal: OrderService, PaymentGateway, ..."

Requirements

LLM model size recommendation: 8B+ parameters minimum, 14B+ for reliable tool calling, 70B+ for complex view composition workflows.

Installation

1. Download the latest .archiplugin from the Releases page (or the bin/ directory for pre-built artifacts)
2. In Archi: Help > Manage Plug-ins > Install New... or copy to Archi's dropins/ folder
3. Restart Archi

Getting Started

1. Start the Server

Open an ArchiMate model in Archi, then:

Menu: MCP Server > Start MCP Server

The MCP Server entry in Archi's menu bar has three items:

Server behaviour (port, bind address, TLS, authentication, …) is configured separately under Window > Preferences > MCP Server — see Configuration. The default endpoint is http://127.0.0.1:18090.

2. Configure Your LLM Client

Claude Code (CLI)

In your project's .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "archi": {
      "type": "http",
      "url": "http://127.0.0.1:18090/mcp"
    }
  }
}

Or via the CLI:

claude mcp add --transport http archi http://127.0.0.1:18090/mcp

Claude Desktop

Claude Desktop does not natively support Streamable HTTP, so a proxy is required. Install uv (a single Rust binary), then add to your claude_desktop_config.json:

Windows:

{
  "mcpServers": {
    "archi": {
      "command": "C:\\Users\\YOUR_USER\\.local\\bin\\uvx.exe",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://127.0.0.1:18090/mcp"]
    }
  }
}

macOS:

{
  "mcpServers": {
    "archi": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://127.0.0.1:18090/mcp"]
    }
  }
}

Cline / Other MCP Clients

Point your MCP client at the Streamable-HTTP endpoint:

http://127.0.0.1:18090/mcp

SSE transport is also available at /sse for older clients.

3. Start Querying

With the server running and your LLM client connected, you can ask questions in natural language:

• "Give me an overview of this architecture model"
• "Find all Application Services in the model"
• "What does the Order Processing component depend on?"
• "Show me the relationships between the CRM and ERP systems"
• "Create a new view showing the payment processing flow"
• "Auto-layout and route the connections on this view"

Configuration

Access via Window > Preferences > MCP Server in Archi.

TLS / HTTPS

The server supports optional TLS encryption. To enable:

1. In preferences, check Enable TLS (HTTPS)
2. Click Generate Self-Signed Certificate to create a keystore automatically
3. Restart the server — the endpoint changes to https://127.0.0.1:18090

Clients must trust the self-signed certificate. For curl testing, use the -k flag. For LLM clients, import the certificate into the client's trust store or the JVM cacerts.

The keystore password (whether you type it or generate it with the button) is stored in your OS keychain via Equinox secure storage — the same store the bearer token and Archi itself use — not in the plaintext preference file. If you had a keystore password set in an earlier version, it is migrated automatically on first start.

Enabling authentication (bearer token)

By default the server requires no authentication — anything that can reach the port can call the tools, which is why the default bind is loopback only. If you bind to a non-loopback address, or simply want a secret required even on loopback, enable an opt-in bearer token:

1. In Window > Preferences > MCP Server > Authentication, check Enable bearer-token authentication. A 256-bit token is generated automatically on first opt-in and stored in your OS keychain (via Equinox secure storage — no separate password to manage).
2. Click Copy to copy the token, or Generate / Regenerate token to roll it (regenerating invalidates clients still using the old token).
3. Restart the server. Every request to /mcp and /sse must now send Authorization: Bearer <token>; a missing, malformed, or wrong token gets 401.

Configure your clients to send the header:

Claude Code (CLI):

claude mcp add --transport http archi http://127.0.0.1:18090/mcp --header "Authorization: Bearer <token>"

Claude Code (.mcp.json / ~/.claude.json):

{
  "mcpServers": {
    "archi": {
      "type": "http",
      "url": "http://127.0.0.1:18090/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Claude Desktop (via mcp-proxy) — pass the header through the proxy:

{
  "mcpServers": {
    "archi": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "--headers", "Authorization", "Bearer <token>", "http://127.0.0.1:18090/mcp"]
    }
  }
}

curl (testing):

curl -X POST http://127.0.0.1:18090/mcp -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Authentication is off by default — existing configs without an Authorization header keep working unchanged until you enable it. On a non-loopback bind, also enable TLS so the token is not sent in cleartext.

Security model

The server exposes mutating and file-touching tools over HTTP, so the trust boundary is worth understanding. SECURITY.md states what the server protects against by default (loopback bind, Origin/Host validation, request/session/image resource limits, UTF-8 request-body enforcement, the human-owned approval gate) versus what is your responsibility as the operator (transport encryption, client authentication, securing a non-loopback bind), and how to report a vulnerability. Read it before binding off-loopback or pointing an agent at untrusted input.

Available Tools

The server exposes 69 MCP tools organised into functional categories.

Query & Model Inspection (6 tools)

Search & Discovery (4 tools)

Element & Relationship Creation (4 tools)

Element, Relationship, View & Model Updates (4 tools)

ArchiMate Specializations (5 tools)

Specializations are IS-A subtypes of ArchiMate concept types (e.g. "Microservice" is a kind of ApplicationComponent, "Cloud Server" is a kind of Node). Use them to classify the kind of thing an element is — not for per-instance attributes like environment or version. See archimate://reference/archimate-specializations for the full guide.

View Composition (9 tools)

All view-composition tools that place a new visual object (add-to-view, add-group-to-view, add-note-to-view, add-view-reference-to-view, add-image-to-view) and update-view-object accept the full visual styling surface: fill / line / font colour, opacity, line width, line style (solid / dashed / dotted / none), typography (fontName, fontSize, fontStyle), gradient, deriveLineColor, outlineOpacity, figureType (rectangular / tabbed), textAlignment, verticalTextAlignment, plus note-specific borderType (dogear / rectangle / none). Existing calls are byte-identical; supply only the fields you want to set. Every one of these fields reads back through get-view-contents, so a styling mutation can be verified after the write.

When add-to-view or add-group-to-view nests a child inside a container whose fill colour you have not explicitly set, the parent's fill auto-recedes to a subtle backdrop (#F4F4F4) so the nesting reads as depth instead of a flat block. The recession is provenance-gated and idempotent (only an unauthored fill is touched; an explicitly coloured container is left untouched), rides the placement as one undo unit, and excludes the root view. Pass recede: false to suppress it for a call.

A view object can also anchor to a target container via update-view-object, recording an {anchorTarget, anchorEdge, dx, dy} so its position resolves from the target's current bounds at commit time rather than a frozen snapshot — edge below (default) tracks the target's growing bottom, above/right/left the corresponding edge. When a later mutation moves or grows the target, every anchored object is repositioned within the same undo unit. Target and object must share a coordinate space; self-anchors and cross-space anchors are rejected. add-note-to-view's content-relative placement uses the same edge resolver.

View Cleanup (2 tools)

Layout & Routing (11 tools)

LLM agents: Fetch archimate://prompts/routing-preconditions-checklist before invoking auto-route-connections or auto-layout-and-route on any non-trivial view. The routing pipeline cannot recover from missing preconditions — it can only route the geometry the agent has set up. The spacing convenience tools self-terminate honestly: if a view is provably too dense for spacing to fix they return terminationReason: density_floor_reflow_required and offer a user-consentable structural reflow — surface that to the user instead of looping the spacing tools.

Layout Assessment & Analysis (2 tools)

Metric acronyms below — M1–M6, R8, parallelConnectionGap_V_p10 (V_p10), HPQ — are defined in the glossary.

View Operations (1 tool)

Folder Management (5 tools)

Deletion (4 tools)

Export (1 tool)

Images (2 tools)