Archi Mcp Server

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

| Requirement | Version | |---|---| | Archi | 5.7+ | | Java | 21+ | | An MCP-compatible LLM client | Claude CLI, Cline, LM Studio, etc. |

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](../../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:

| Menu item | What it does | |---|---| | Start MCP Server | Starts the embedded server; toggles to Stop MCP Server while running. | | Approval Mode | Checkable toggle for the human-owned approval gate. When on, the agent's changes queue for your review instead of applying immediately — see [Mutation Safety](#mutation-safety). | | Pending approvals (N) | Opens the Pending Approvals dock view; N is the live count of changes awaiting your decision. |

Server behaviour (port, bind address, TLS, authentication, …) is configured separately under Window > Preferences > MCP Server — see [Configuration](#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.

| Setting | Default | Description | |---|---|---| | Port | 18090 | HTTP(S) server port | | Bind Address | 127.0.0.1 | Network interface (localhost only by default) | | Auto-Start | false | Start the server automatically when Archi launches | | Log Level | INFO | Logging verbosity: DEBUG, INFO, WARN, ERROR | | Enable TLS | false | Use HTTPS with TLS encryption | | Keystore File | (empty) | Path to PKCS12/JKS keystore (auto-generated if using self-signed) | | Keystore Password | (empty) | Password for the keystore file, stored in your OS keychain via Equinox secure storage (no separate password to manage) — never written to disk in cleartext | | Enable bearer-token authentication | false | Require an Authorization: Bearer header on every request (see below) |

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 ; 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 "

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

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

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

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

curl (testing):

curl -X POST http://127.0.0.1:18090/mcp -H "Authorization: Bearer " -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](SECURITY.md) states what the server protects against by default (loopback bind, Origin/Host validation, request/session/image resource limits, 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)

| Tool | Description | |---|---| | get-model-info | Model overview — name, purpose, custom properties, element/relationship/view counts by type and layer, plus specialization count. Read counterpart to update-model | | get-element | Retrieve element(s) by ID (single via id or batch via ids array) | | get-views | List views with optional viewpoint type or name filtering | | get-view-contents | View diagram contents — elements, relationships, visual positions, connection routing, image visuals, and the full styling surface (typography, gradient, alignment, line style, labelExpression) so styling mutations can be read back and verified. format: "tree" returns the containment hierarchy, descending both visual groups and ArchiMate-element containers — nested children appear in the parent node's children array with a childCount. Graph nodes and edges also carry their visual identifiers (viewObjectId on nodes, viewConnectionId on edges) so a returned visual can be fed straight into remove-from-view / update-view-object / update-view-connection without a second lookup | | get-relationships | Traverse relationships with configurable depth (0-3 hops) or multi-hop chain traversal with direction/type/layer filters | | find-concept-usage | Reverse where-used lookup — given an element or relationship ID, returns every view and visual object/connection that references it. Inverse of get-view-contents. Use before delete-element / delete-relationship / rename / re-type to see the cross-view footprint in one round-trip |

Search & Discovery (4 tools)

| Tool | Description | |---|---| | search-elements | Full-text search across element names, documentation, and properties with optional type, layer, and specialization filters | | search-relationships | Search all relationships by text, type, source/target element layer, and specialization — no element ID needed | | get-or-create-element | Discovery-first — returns existing element if exact name+type match exists, otherwise creates new | | search-and-create | Combined search + conditional create with duplicate candidate display |

Element & Relationship Creation (4 tools)

| Tool | Description | |---|---| | create-element | Create an ArchiMate element with type validation and duplicate detection. Optional specialization parameter auto-creates the specialization on first use | | create-relationship | Create a relationship with ArchiMate specification rule enforcement. Optional specialization parameter auto-creates the specialization on first use. Optional type-conditional semantic attributes: accessType (AccessRelationship), associationDirected (AssociationRelationship), influenceStrength (InfluenceRelationship) | | create-view | Create a new diagram view with optional viewpoint and connection router type | | clone-view | Duplicate an existing view with all visual contents (elements, groups, notes, connections, bendpoints, styling). The clone references the same model objects |

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

| Tool | Description | |---|---| | update-element | Update element name, documentation, properties, or specialization (pass "" to clear) | | update-relationship | Update relationship name, documentation, properties, or specialization (pass "" to clear). Optional type-conditional semantic attributes: accessType (AccessRelationship), associationDirected (AssociationRelationship), influenceStrength (InfluenceRelationship). Source, target, and type are immutable | | update-view | Update view name, viewpoint, documentation, properties, or connection router type | | update-model | Update the loaded model's own name, purpose, and custom properties as a single undo unit. At least one of the three must be provided; omitted fields stay unchanged. Empty-string purpose clears the field; null property values remove a key |

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.

| Tool | Description | |---|---| | list-specializations | List every specialization defined on the model with (name, conceptType, layer, usageCount, imagePath). Optional conceptType filter | | create-specialization | Define a specialization explicitly without creating any element. Idempotent on duplicate (name, conceptType) — useful for pre-registering vocabulary at session start. Optional imagePath sets the specialization's icon (Archi renders it on every concept of that specialization) | | update-specialization | Rename a specialization and/or set its icon. Refuses to merge into an existing target name. Existing references move with the rename. Optional imagePath (set/change icon) and clearImagePath: true (explicit clear) — mutually exclusive. At least one of newName, imagePath, or clearImagePath must be supplied | | delete-specialization | Delete a specialization. Refuses by default if any concept uses it; pass force: true to detach references and delete in one atomic command | | get-specialization-usage | Audit query — lists every element and relationship referencing a specialization. Call before rename or delete |

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.

| Tool | Description | |---|---| | add-to-view | Place a model element onto a view diagram (same element can appear on multiple views). Optional imagePath, imagePosition, showIcon for custom icon overlays, and labelExpression for a per-view-object dynamic label template (e.g. "${name}", "${property:Owner}") | | add-group-to-view | Add a visual grouping rectangle (pure visual container, no model representation). Optional imagePath, imagePosition, and showIcon for custom icon overlays | | add-note-to-view | Add a text note annotation (pure visual, no model representation). Optional imagePath, imagePosition, showIcon, and note-specific borderType | | add-view-reference-to-view | Embed another ArchiMate view as a clickable thumbnail (the agent-driven equivalent of Archi GUI's drag-view-onto-view). Requires viewId (target) and referencedViewId (source). The referenced view's name is not stor

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fanievh
• Source: fanievh/archi-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.