Installation Guide

This guide covers:

The JShell workflow is documented and packaged only as an experimental path. Do not propose it by default unless the user explicitly opts into direct Java API experiments.

For the components, communication paths, and local security controls, see Obeo AI for Capella Architecture.

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:

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.

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.

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 diagnostics and manual fallback, see the MCP reference.

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

Client-specific settings are maintained in the LLM client configuration guide.

The agent archive includes docs/experimental/jshell.md for advanced experiments with the Java client APIs. Treat this as experimental. Do not use or propose it by default in an AGENTS.md-driven workflow.

If a user wants to test it, they should explicitly modify their project AGENTS.md or startup instructions, start JShell manually with the packaged libraries and paste or adapt the snippets from the experimental guide, or use the experimental launchers under bin/experimental/ that preload the matching startup script from docs/experimental/jshell/scripts:

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: