Installation Guide

This guide covers:

For connection modes and the required permissions, see Transport and access rights.

The distribution archives use a build version such as x.y.z.YYYYMMDDHHMM. In this guide, replace x.y.z.YYYYMMDDHHMM with the version from the archive you downloaded. For example: 2026.9.0.202609041200.

The archive layout uses these names:

Before installing Obeo AI for Capella, check the following requirements. Installation steps are provided in the Installation Guide.

See Supported environment for software, access and connection requirements.

SMW installations on Windows keep the capella folder but use SMW.exe. A bundled jre folder is not present in every SMW distribution, even when the underlying Capella version is 7.1.0. Use the separate Java 21 setup below whenever no suitable runtime is bundled, including for Capella 7.0.1 and 6.1.0.

The installer runs Capella or SMW with the runtime configured for that product. SMW must already be able to start with its customer-provided Java configuration. The Java 21 setup below configures only the MCP and CLI tools; it does not change the runtime used by Capella or SMW.

The parent folder should look like this:

For SMW, keep the capella folder name and the existing SMW.exe name. The installer selects capella.exe when present, otherwise SMW.exe. It uses the matching console launcher (capellac.exe or SMWc.exe) if available, otherwise the selected product executable. The same selection is used for discovery, uninstallation, and installation of the automation features.

The script installs the Sirius and Capella automation features from the bundled update site. It also extracts the agent zip into tools and prints the MCP launch options for stdio and local HTTP. Ecore Tools is not installed by default. The installer identifies Capella from its org.polarsys.capella.rcp_<version> feature before changing the installation. It accepts versions 7.1.0, 7.0.1 and 6.1.0 and reports the selected Java 21 path for the tools after extraction. The version check uses the underlying Capella version, including for SMW. If Java 21 is missing, the Capella features remain installed; configure Java before connecting the desktop client.

For Linux or macOS, extract the Unix archive:

Extract into the folder containing capella. The archive places tools, updateSite, LICENSE, and EULA.html directly in that destination, without an enclosing distribution folder. Keep this layout:

On macOS, open Terminal; on Linux, open a terminal. Run, replacing <installation-folder-absolute-path> with your absolute installation path:

For a native macOS application, right-click the Capella application in Finder and select Show Package Contents. Place tools and updateSite inside Contents, alongside MacOS, Eclipse, and jre:

In the command above, <installation-folder-absolute-path> is the full path to Capella.app/Contents. The script reads the RCP feature from Eclipse/features in this layout. For the classic layout, it reads capella/features. If MacOS/capella is not present, the script falls back to capella/capella. The same Capella version and Java checks apply on Windows, Linux, and macOS.

After installation, the script prints the exact capella-mcp commands for both stdio and local HTTP, plus the path to this guide inside the extracted agent.

Complete the Windows or Linux/macOS installation above first, then start Capella. If you already have your personalized license archive, skip the request step.

To request a license, select Help > Register Obeo AI for Capella. Send the registration information to registration@obeo.fr to obtain your personalized license archive.

To install the license supplied by Obeo:

After installation, choose how your AI coding assistant connects to capella-mcp. Capella is needed for runtime discovery and model operations; the MCP connection and guidance check can run before starting it.

Use only the aggregate capella-mcp server for Capella work; it includes the required Sirius and EMF tools. Configure one connection route for the initial check. A hosted client cannot launch a command on your computer or access its loopback address; use a reachable HTTPS endpoint for remote access.

Three deployment modes are supported:

The following client and transport combinations have been tried. This list includes CLIs, desktop applications and IDE integrations; it is not an exhaustive compatibility guarantee. The selected client must allow you to add your own MCP server and invoke its tools.

For client setup examples, see LLM Client Configuration.

The available trial records did not distinguish between the listed Codex or Claude surfaces for stdio. Check the exact surface before treating either stdio entry as a surface-specific compatibility guarantee. These connection records do not establish automatic guidance loading. Use the startup checks to verify document retrieval in the exact client and version in use.

Local HTTP is useful when you want to control exactly when the MCP server starts and stops, or when an assistant context does not support stdio or process-based tools correctly. Use HTTPS with bearer authentication when the MCP endpoint must be reachable beyond the local host.

The installer prints ready-to-use commands for stdio and local HTTP using the extracted agent path. Use those generated paths in preference to the generic examples below.

By default, Capella asks for approval when a local automation client connects. For demos or controlled local automation sessions, launch Capella with this VM argument to accept local automation connections without the approval window:

Example paths in the sections below must be adapted to your installation.

Windows:

Linux/macOS:

Use stdio when your AI coding assistant can launch the MCP server process. capella-mcp uses stdio by default, so no --transport option is required. The client owns the process lifecycle; do not also start it in a terminal. Keep stdout reserved for MCP messages; diagnostics go to stderr. The examples below use the optional read-only profile for a restricted installation check; leave arguments empty to use the default desktop setup.

Windows command path:

Linux/macOS command path:

Use local HTTP when you want to launch and control the MCP server process yourself, or when the AI coding assistant cannot use stdio/process tools.

Windows:

Linux/macOS:

The HTTP MCP endpoint is:

Use 127.0.0.1 in MCP client configurations instead of localhost. This is intentional: clients launched from WSL or from another local network context may not resolve localhost to the same loopback interface as the Capella MCP server.

Keep the terminal process running while the client is connected. Unlike stdio, the client does not start or restart this server. Change its profile by restarting the process and reconnecting the client to refresh its tool catalog. The default profile, if omitted, is edit.

If CAPELLA_MCP_AUTH_TOKEN (or AUTOMATION_MCP_AUTH_TOKEN) is set in the server environment, configure the client to send the same token as Authorization: Bearer <token>, including on resource requests. See the client configuration guide for client settings. If both server variables are set, AUTOMATION_MCP_AUTH_TOKEN takes precedence. See HTTPS and token configuration for remote access. A hosted client cannot reach this machine’s loopback URL directly.

The MCP server rejects plain HTTP bound to a non-loopback address. A remote MCP endpoint must use HTTPS, and remote HTTPS requires a bearer token. Although a token is optional for loopback HTTPS, using one there as well makes the local test representative of a remote deployment.

Prefer supplying the token through CAPELLA_MCP_AUTH_TOKEN instead of --auth-token, because command-line arguments can be visible in shell history and process listings. AUTOMATION_MCP_AUTH_TOKEN is the equivalent generic environment variable and takes precedence when both variables are set.

The HTTPS server accepts a PEM certificate chain through --cert and the matching PEM private key through --key. Use --key-password when the private key is encrypted.

This guide provides settings for connecting your AI client to Capella MCP. For installation, the user manual and release notes, see the Obeo AI for Capella documentation.

Install the product using the installation guide first. You need an agentic AI client that can add a custom MCP server and invoke its tools. The client combinations tried cover CLIs, desktop applications and IDE integrations. Check that your chosen client supports the local command or server URL used by your connection mode. Choose a transport and server profile before applying the client-specific examples below. These settings retain the client versions and limitations recorded in the original guides; client UI labels can change. The desktop quick start uses the default edit profile; examples explicitly requesting read-only restrict the available tools.

See Transport and access rights for process permissions, connection approvals and the account used for model operations.

Examples use Windows launchers by default. Replace <installation-folder-absolute-path> with your absolute installation path and x.y.z.YYYYMMDDHHMM (or <version>) with your extracted agent version. On Linux/macOS, use forward slashes and capella-mcp instead of capella-mcp.cmd; invoke the launcher directly rather than through cmd.exe. See Paths and executable names for the Java, Capella, CLI and installer equivalents. Escape Windows backslashes in JSON and double-quoted TOML strings.

Use the same startup sequence for stdio and HTTP/HTTPS. The server already sends instructions directing the assistant to load its guidance. No workspace instruction file or pasted startup block is required when the client follows them; automatic retrieval must be verified for the client in use.

An empty list is valid for an empty workspace. This check does not require a model summary or exploration of model contents.

For ongoing conversations and requesting model changes, see Working with Capella. For guidance-loading recovery, see If Guidance Was Not Loaded and the manual document fallback.

If you selected a restricted profile, follow Server Profiles to enable editing when needed.

CLI and MCP servers write warnings and errors, including exception traces, to stderr. For stdio, the MCP host may capture this output; for HTTP, check the terminal or service manager. MCP file logging is disabled by default: Logback creates no log files or directories. Existing log files are left untouched.

Logging configuration is in the extracted agent directory, tools/sirius-automation-agent-x.y.z.YYYYMMDDHHMM/:

Edit the appropriate XML and restart the application. To enable optional MCP file logging in conf/mcp/logback.xml:

The sample directory is ${user.home}/.obeo-ai/logs. Files are named capella-mcp.log or sirius-mcp.log, with compressed archives under archived/. The sample rotates at 10 MB per file, retaining seven days of archives with a 100 MB archive limit per server. Adjust these values in the XML if needed.

To select an alternative XML file, launch Java directly from the agent directory: