Obeo AI for Capella - Desktop Client Quick Start

This guide configures Obeo AI for Capella with an MCP-compatible desktop LLM client on the same computer, using a local STDIO connection. Client-specific settings are kept in the separate LLM client configuration guide.

1. Prerequisites

You need:

  • Capella 7.1.0 (target version); installation also supports 7.0.1 and 6.1.0;

  • the Obeo AI for Capella package provided by Obeo;

  • a desktop client supporting local MCP servers over STDIO, such as ChatGPT desktop.

Standard Capella 7.1.0 includes Java 21. The MCP launcher uses this bundled runtime unless AUTOMATION_SERVER_JAVA_HOME is set or a usable Java 21 runtime is provided under tools/jre. For SMW without a bundled Java 21, Capella 7.0.1 or 6.1.0, or a custom runtime, follow Java setup.

2. Install Obeo AI for Capella

Extract the package so that capella, tools, and updateSite are in the same parent folder:

<installation-folder-absolute-path>/
  capella/
  tools/
  updateSite/

On macOS, the Capella executable may instead be located under MacOS/capella, as described in the installation guide.

Windows

SMW installations keep the same capella folder; the installer also detects SMW.exe.

Double-click <installation-folder-absolute-path>\tools\install_automation_server_in_capella.bat. To keep errors visible, open the Start menu, type cmd, open Command Prompt (Invite de commandes on French Windows), and run:

cd /d "<installation-folder-absolute-path>"
tools\install_automation_server_in_capella.bat

Linux or macOS

On macOS, open Terminal; on Linux, open a terminal. Run:

bash "<installation-folder-absolute-path>/tools/install_automation_server_in_capella.sh"

Replace <installation-folder-absolute-path> with the absolute path to your installation.

3. Request and install your license

Complete section 2 first, then start Capella. If you already have your personalized license, skip the request and install it below.

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:

  1. In Capella, select Help > Install New Software.

  2. Select Add > Archive and choose the personalized license archive.

  3. Select the license feature, complete installation, and restart when prompted.

4. Configure your desktop client

Follow the LLM client configuration guide for your client. It contains the ChatGPT desktop example and alternative clients. Configure the absolute path to the installed capella-mcp launcher and select STDIO. The desktop client starts the MCP server automatically; return here to verify the installation.

5. Verify the installation

Start Capella. Confirm that your desktop client reports capella-mcp as connected. If the client exposes MCP prompts, you can select capella_init (Start Capella modeling) first to add startup instructions to the conversation; see Use the optional startup prompt. Then send this request:

Connect to the running Capella instance and list its projects. For this initial connection check only, do not inspect model contents or diagrams, and do not modify anything.

Approve the local automation connection in Capella if prompted. The assistant should list the projects; an empty list is valid for an empty workspace. The server supplies guidance-loading instructions; actual loading depends on the client. If retrieval is missing or unconfirmed, use If Guidance Was Not Loaded, then retry. Skip this fallback when guidance is already loaded. No local guidance-file copy is required.

Continue with Working with Capella to request model changes and review the results.

6. Troubleshooting

If the connection fails, check that:

  • the configured launcher path is correct;

  • Java 21 is available from the product or the alternative Java setup;

  • Capella is running;

  • your Obeo AI for Capella license is installed and valid;

  • the local automation connection is approved when prompted.

For Windows installation errors, run the .bat from Command Prompt (cmd) as shown in section 2 to keep the messages visible.

For further help, see the installation guide’s troubleshooting section.