User Manual

Obeo AI for Capella connects compatible AI assistants to a running Capella environment. Use it to explore, understand, analyze, modify, document and verify architecture models.

  • Quick start: install the product, connect a client and verify the connection.

  • Release notes: changes and documented limitations.

For Java, licensing, server transports and troubleshooting, use the installation guide. For client connection settings, see LLM client configuration.

1. Features

1.1. What Obeo AI for Capella Does

Obeo AI for Capella connects compatible AI assistants to a running Capella environment so engineers can explore, understand, analyze, modify, document, and verify architecture models.

The recommended workflow is:

Explore -> Understand -> Analyze -> Decide -> Modify -> Verify

1.2. What You Can Do

Describe your goal directly to the AI assistant. You do not need to choose individual tools.

Capability What you can do Example request

Explore projects and models

Discover projects, inspect model structure, and understand the current selection.

“Show me the projects in this workspace and explain the selected component.”

Work on diagrams

Find, create, open, and inspect supported diagrams and their contents.

“Open the logical architecture diagram and explain its components and connections.”

Use diagram palette tools

Create visible elements and connections, or insert existing elements using supported palette selection tools.

“Add the existing logical function to this diagram using its palette tools.”

Edit model elements

Create or update supported elements and properties. Specify whether changes should also appear in a diagram.

“Create a logical component named Monitoring and make it visible in this diagram.”

Analyze impacts

Examine dependencies, affected elements, and representations to support engineering decisions.

“Which elements and diagrams would be affected by changing this component?”

Maintain traceability

Inspect and complete supported realization links between architecture layers.

“Review the realization links between these system and logical functions and complete the clear mappings.”

Document the architecture

Read and update descriptions on model elements and diagrams.

“Document this component’s responsibility and update the diagram description.”

Prepare diagrams for review

Refresh, arrange, inspect, and export supported diagrams.

“Refresh and arrange this diagram, then export it as a PNG for review.”

For modeling workflows, see Working with Capella, including model elements and diagram content, realization links, and reviewing and saving changes.

1.3. Known Limitations

Available palette operations depend on the diagram and selected elements. See Known Limitations for current restrictions, particularly scenario diagrams and palette tools that open dialogs.

1.4. Multi-Step Operations

When an operation contains several steps, execution stops at the first error. For operations that change the model, completed changes remain applied and are not automatically rolled back. Inspect the model and diagrams before retrying to avoid duplicate changes; see Review and Save.

1.5. Deployment and Compatibility

The following client and transport combinations have been tried. This list is not an exhaustive compatibility guarantee.

Transport Clients tried

HTTP

Codex CLI; Gemini CLI (Enterprise/API); Qodo IDE plugin; Kiro IDE

stdio

ChatGPT desktop app / Codex CLI; Claude Code / Claude Desktop; Antigravity IDE; VS Code Chat on Windows

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.

The default transport is stdio. Local HTTP binds to 127.0.0.1 by default. Remote plain HTTP is rejected; remote HTTPS requires a bearer token. The server also supports allowed-origin and allowed-host restrictions.

The MCP and CLI tools require Java 21, included with standard Capella 7.1.0. Installation targets Capella 7.1.0 and also supports 7.0.1 and 6.1.0 on Windows, Linux, and macOS. Older Capella versions and SMW distributions without a bundled Java 21 need a separate Java 21 for these tools; see the Java setup instructions.

Local deployment does not guarantee that model data remains on the local machine: the configured AI client or model provider determines what context is sent outside the environment.

2. Working with Capella

Use this guide once your desktop client is connected. For setup, follow the quick start or installation guide.

2.1. Start a Conversation

Confirm that your client reports capella-mcp as connected. Start Capella and open the project you want to work on. In a new conversation, describe your task directly. The server already supplies startup instructions directing the assistant to load its guidance; no pasted startup prompt or workspace instruction file is required when the client follows them.

For a lightweight connection check, ask the following. This check requires a running Capella instance, but no open model or diagram:

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. An empty project list is valid; no model summary is needed for this check.

Check that the guidance resource or tool results contain both the operating contract and Arcadia context. If retrieval did not happen or cannot be confirmed, use the fallback below, then retry the project-list request. Guidance retrieval itself needs no running Capella instance.

2.1.1. Use the optional startup prompt

Some clients expose prompts provided by a connected MCP server for you to select. The Capella MCP server provides the no-argument prompt capella_init, titled Start Capella modeling. You can select it at the start of a conversation to insert the initial Capella instructions.

For example, in Claude Code, type / after connecting the server and select /capella-mcp:capella_init when the configured server name is capella-mcp. If you registered the server under another name, use that name in the command. See Claude Code prompt commands.

The prompt itself does not connect to Capella or retrieve the extended operating contract and Arcadia context. Follow its instructions, then use the guidance-loading and connection checks above before continuing with your modeling task. This shortcut is optional: clients without prompt support can use the normal startup flow and the fallback below when guidance retrieval is missing or unconfirmed.

2.1.2. If Guidance Was Not Loaded

Paste this block when guidance retrieval did not happen or cannot be confirmed. Skip it when both documents are already loaded in the current conversation.

Before working with Capella, read the MCP resources
capella://guidance/operating-contract and capella://guidance/arcadia.
If resource reading is unavailable or fails, discover and call
capella_get_agent_guidance with no arguments.
Use the retrieved guidance for Capella work. If neither route succeeds,
report the problem and do not modify the model. Troubleshoot guidance
retrieval before continuing model work.

2.1.3. Where To Put The Fallback Prompt

Use If Guidance Was Not Loaded only when needed. For a client that consistently needs this fallback, append the short block to its existing project instructions; preserve all other project guidance. Do not repeat it or fetch the documents again when they are already in context.

Client surface Where to supply the fallback when needed

Codex local app, CLI, or IDE extension

A chat message, or a block in project AGENTS.md. MCP configuration is separate.

ChatGPT desktop with a local Codex host

Use that host’s MCP configuration and supply the fallback in the local task.

Hosted ChatGPT

Make Capella tools available through a supported remote integration; supply the fallback in the chat. Local Codex configuration and loopback URLs do not configure the hosted client.

Claude Code

A chat message, or a block in project CLAUDE.md. Resource reading is supported; @ references are also available.

Claude Desktop

A chat message after enabling its MCP connection. Validate this surface separately from Claude Code.

Other MCP clients or custom agents

Use their supported instruction/context mechanism. Read resources if exposed to the agent; otherwise use the guidance tool. With a custom agent, application code can fetch the documents before starting the modeling task.

These routes depend on the client in use; they are not a compatibility guarantee.

2.1.4. Manual Document Fallback

If neither live route can supply the documents, report the missing guidance and do not modify the model. Troubleshoot retrieval before continuing model work. The user can explicitly provide the full packaged docs/templates/capella-mcp/AGENTS.md and neighboring CAPELLA_ARCADIA_CONTEXT.md as attachments or readable local files. Preserve existing project instruction files; do not overwrite them with the full contract. Ask the agent to read the supplied documents. Providing files does not restore a missing MCP connection or grant access to model-editing tools.

The templates are embedded in the MCP JAR; updating a copied Markdown file does not update a running server. Operators must install an updated package and restart the MCP process to receive new guidance.

2.2. Inspect the Model

Once guidance is loaded, safe inspection can proceed directly. Request only the model inspection needed for your task. Name the project, architecture layer, or diagram when several could match. You can ask for explanations and reviews without authorizing model changes.

2.3. Request Changes

Describe the intended result and its scope: which model elements or diagram should change, and what should be preserved. For example:

In the open LAB, add a logical function named Monitor Status to the selected component and make it visible in the diagram. Keep the existing content.

An edit request authorizes safe, clear changes within that scope. The assistant should clarify ambiguous targets and ask before destructive or additional work. Switching between the available Capella, Sirius, and EMF tools does not by itself require extra confirmation. If editing tools are unavailable, check the configured server profile.

2.3.1. Model Elements and Diagram Content

Creating a model element does not automatically make it visible in a diagram. State whether you want semantic-only changes or visible diagram content. For visible creation, the assistant should use the diagram’s available palette tools and verify both the model element and its view. Direct element creation is a fallback when semantic-only content is requested or the diagram route is unavailable or unsuccessful; it does not guarantee a view. A missing view should not be compensated for by creating a duplicate model element.

For work spanning several architecture layers, the default progression is OA, SA, LA, PA, then EPBS within the requested scope. Existing layers and iterative refinement determine the appropriate starting point.

For realization work, you can ask:

Review the realization mapping between these system and logical functions. Complete the clear, supported links and report uncertain mappings.

The assistant should proactively identify useful links and apply unambiguous, supported ones within requested mapping, traceability completion, or derivation work. It should clarify uncertain mappings, inspect existing links to avoid duplicates, and propose additional opportunities with their rationale outside that scope, asking once for the group. A read-only review proposes links without creating them. Matching names alone do not justify a realization link.

Native Capella transitions derive downstream content from existing upstream elements. An explicit, unambiguous transition request authorizes its inherent realization links, including links to new targets. The assistant should clarify ambiguous transition scope or options before execution.

2.4. Known Limitations

2.4.1. Component Exchange to Functional Exchange Allocation

Allocating functional exchanges to a component exchange is currently unsupported through MCP. Use Capella’s Allocated Functional Exchanges property field for this operation.

2.4.2. Sirius Sequence and Capella Scenario Diagrams

Editing Sirius Sequence diagrams, including Capella Scenario diagrams, is not supported through MCP beyond the operations listed below. Their layout is strongly coupled to the semantic ordering of elements.

You can create these representations, open and inspect them, and update descriptions, attributes, and references that do not affect events or their ordering. Perform layout changes and any edits that create, delete, modify, or reorder events directly in Capella. Other edits affecting semantic ordering must also be performed in Capella.

2.4.3. Palette tools and actions that open dialogs

Some palette tools, actions, or menu commands that normally open a wizard, popup, or dialog in Capella can fail with Invalid thread access when invoked through MCP. The affected actions are not yet fully identified; this does not mean that all dialog-based actions are unsupported. In particular, supported Sirius palette selection tools accept selections through MCP without opening a dialog. Record the exact MCP tool name, the requested action, and the returned error message. Inspect any partial changes before retrying or completing the operation directly in Capella; do not assume the failed call left the model unchanged.

2.5. Review and Save

Review the changed elements and diagrams in Capella. The assistant should verify each coherent change before proceeding, including semantic changes, realization links, and requested diagram content. For transitions, this includes checking created or reused targets and their links, and exposing result elements in diagrams when requested. It should report incomplete or uncertain results and distinguish existing content from new work. A realization link records a relationship; it does not prove that requirements are satisfied.

Routine tool feedback should stay compact, with details reserved for decisions, errors, model changes, validation findings, and realization links.

Model changes can remain unsaved; the assistant should report pending changes. Review and save the Sirius session in Capella; there is no dedicated session-save MCP tool. If an operation fails partway, inspect what already changed before requesting a retry, to avoid duplicates.

3. Frequently asked questions

For current connection, Java and license issues, see installation troubleshooting. For model changes and diagram restrictions, see known limitations. Client settings and guidance loading are documented in the LLM client configuration and guidance-loading recovery instructions.

3.1. How do I get access?

Follow the quick start to install the package provided by Obeo and configure your desktop client. Request and install your personalized license as described in Request And Install Your License.

3.2. How do I restore the connection?

Check that the desktop client uses the correct absolute path to the capella-mcp launcher and that Java 21 is available. Start Capella with the automation features installed, check that your Obeo AI for Capella license is installed and valid, and approve the local automation connection when prompted. Restart the desktop client after changing its configuration, then follow the installation verification steps. For HTTP connections, also check the running MCP server, endpoint and configured token. See installation troubleshooting for further checks.

3.3. Why does an operation fail?

Check installation troubleshooting for connection, Java, license and guidance errors. For model edits, check the documented model and diagram restrictions. Record the exact MCP tool name, requested action and returned error message. An operation can fail after applying some changes: inspect the model and diagrams in Capella before retrying or completing the operation manually to avoid duplicate changes.

3.4. Where can I find changes and known limitations?

See the release notes and known limitations.

4. Help and support

4.1. Self-service resources

Consult Frequently asked questions, Getting started and Release notes.

4.2. Contact channels

  • Issue tracker: bug tracker dedicated to your Software Assurance contract.

  • Support email: email dedicated to your Software Assurance contract.

4.3. Report a problem

Report problems through the support channel dedicated to your Software Assurance contract.

Include the product version, environment, steps to reproduce, expected and actual results, and relevant logs. Remove credentials and personal or customer data before sharing diagnostics.