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.”

Create Functional Chains

Build a complete chain from existing Functional Exchanges, or an Operational Process in OA, with an optional view in the source diagram.

“Create a Functional Chain named Monitor Status from these exchanges and show it in this LAB.”

Manage allocations

Add or remove native allocations across all five supported families, without a diagram.

“Allocate these Functional Exchanges to Status Updates and report existing allocations.”

Inspect relationships

Search by name/type, inspect native Semantic Browser relationships and find related diagrams.

“Find the logical actors named Pilot and show their related functions and diagrams.”

Review collections in Capella

Send inspected elements to a new or existing Mass Visualization or Mass Editing view.

“Show these components in a new Mass Visualization view.”

Control diagram layers

Enable or disable layers exposed by a diagram’s native layer selector.

“Enable this layer in the open LAB and preserve the other layers.”

Save reviewed work

Save an explicitly identified session and report its resulting synchronization status.

“Save this session and tell me whether any changes remain pending.”

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.”

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

Palette creation, contextual semantic creation, and element-description batches are atomic: all edits in one call succeed or roll back together. Other edit batches stop on the first failure and retain earlier successful steps. A timeout does not establish whether an edit completed. See batch failure and recovery before retrying, and Review and Save before persisting changes.

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; Tencent Workbuddy; VS Code Chat; OpenCode

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.

Capella 7.1 is the main target version. Installation is also supported on Capella 7.0, Capella 6.1 and the upcoming Capella 2026.11.0 (technical version 7.2.0), on Windows, Linux and macOS.

The MCP and CLI tools require Java 21, included with standard Capella 7.1. Capella 7.0, Capella 6.1 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.

For capability involvement, activity-only process membership, disconnected/cyclic chains, or import gaps, read capella://guidance/modeling-limitations, also available as docs/templates/capella-mcp/MODELING_LIMITATIONS.md. The guidance fallback tool includes this cookbook alongside the operating contract and Arcadia context. It distinguishes current limitations from older benchmark failures and includes expert EMF recipes with focused semantic verification. These recipes do not establish that generic EMF edits enforce all Capella business rules.

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.

For example:

In the open logical architecture, find actors whose names contain Pilot. Show their allocated functions and related diagrams, without changing the model.

The assistant can search directly by name, type, or a known subtree without first reading the whole model. It can inspect native Semantic Browser relationships and related diagrams for selected elements. These relationships help exploration; they are not a guarantee that deleting an element is safe.

Session discovery returns compact diagram identities by default. Diagram inspection can request visible content or palette tools separately, and EMF inspection can select particular properties or references. Larger searches and reference collections are paginated: a partial page or an omitted section is not proof that no other elements exist. Ask for all matches when completeness matters. These controls reduce unnecessary context; they do not establish a fixed token saving or faster execution for every model.

2.2.1. Work with the Current Selection

For a request about “this component,” the assistant can inspect the first selected element in the identified workbench or diagram. Selection inspection does not return the complete multi-selection. For a request about several selected elements, identify the intended set by names or scope; the assistant should clarify rather than silently apply the request to just the first item. Opening an explicitly targeted diagram may activate its editor.

A request to “update this diagram” should distinguish adding visible content, showing existing elements, arranging the layout, or updating documentation. The assistant defaults to visible creation for new model content, reuses an appropriate existing diagram, and asks when the intended target or outcome is materially ambiguous. You can choose semantic-only creation when no diagram view is needed.

2.2.2. Review Collections in Capella

To continue a review in Capella, ask:

Show these components in a new Mass Visualization view so I can compare them in Capella.

The assistant can open a Mass Visualization or Mass Editing view with the exact inspected elements, or append them to an explicitly identified open view. Appending preserves existing contents and avoids duplicate entries. This handoff changes temporary workbench state, not the model or the source selection, and requires the edit profile. Subsequent manual property edits in a Mass Editing view are separate model changes. Review collections are temporary; closing their session clears their contents.

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 a supported native operation, such as Functional Chain creation from diagram edges, or 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.

2.3.2. Diagram Layers

Ask the assistant to enable or disable a named layer in a specific diagram. It discovers the layers exposed by that diagram’s native layer selector and leaves other layers unchanged. Layer changes can alter the visible content and available palette tools; they do not create the semantic elements that a layer displays. Availability and permissions are checked again when the change runs.

2.3.3. Document Model Elements

Ask for descriptions on exact elements, preserving existing text unless replacement is intended. The assistant can update several descriptions in one atomic, undoable operation. A diagram can display a Part usage while the Project Explorer shows its component type: name which one should be documented. For component documentation, the assistant resolves the Part’s type before applying the update. Diagram descriptions are separate from element descriptions. Description changes remain unsaved until the session is saved.

2.3.4. Functional Chains and Operational Processes

Ask the assistant to create a complete Functional Chain from existing Functional Exchanges, or an Operational Process in Operational Analysis. For example:

In this LAB, create a Functional Chain named Monitor Status from these Functional Exchange edges and show it in the same diagram. Reuse the existing exchanges.

For semantic-only creation, specify that no diagram view is needed. The assistant can discover exchanges through model inspection without opening a diagram. The selected exchanges must form a connected, acyclic functional graph and belong to the supplied session with resolved function endpoints.

The assistant uses capella_apply_model_edits with a create_functional_chain step and explicit runtime, session, and chain name. It supplies exactly one of:

  • Semantic Functional Exchange IDs (exchangeIds), with an optional semantic container (ownerId). If omitted, Capella uses the native root-function owner. This form creates no view.

  • A source representation descriptor UID (diagramId) and its Functional Exchange edge view IDs (exchangeViewIds). This form creates both the chain and its view in a source diagram that supports native chain views. The owner follows the diagram context; no ownerId is accepted.

The result supplies reusable chain and owner identities, plus diagram and view IDs for diagram creation. Each creation is one undoable transaction, including the optional view. A failed creation rolls back that step; earlier successful batch steps remain applied. Creation leaves the session unsaved. Repeating a successful request creates another chain, so inspect existing content before retrying.

A Functional Chain Description diagram (XFCD, such as an LFCD) is a separate representation. Ask for it after creation or for an existing chain whenever needed. The assistant discovers the definition from the chain’s semantic context, verifies a creation candidate, and uses the existing Sirius representation tools. These definitions belong to the Common viewpoint and may be absent from an architecture-filtered catalogue.

To show an existing chain in another diagram, use its compatible palette insertion/selection tools and select that chain; do not create a duplicate chain. To modify or sequence a chain, use native palette tools in its XFCD. Available operations and candidates depend on the target diagram and permissions. The assistant must discover them and preserve existing involvements rather than rebuild the chain.

2.3.5. Allocation Management

Ask the assistant to add or remove allocations between existing elements. For example:

Allocate these two Functional Exchanges to the existing Component Exchange Status Updates. Reuse the exchanges and report which allocations changed. No diagram change is needed.

The supported allocating source to allocated target pairs are:

  • Component or Operational Role to Function or Operational Activity.

  • Interface to Exchange Item.

  • Component Exchange to Functional Exchange.

  • Physical Link to Component Exchange.

  • Physical Part deployment location to deployed Physical Part usage.

The assistant discovers exact semantic IDs and inspects existing relationships before calling capella_apply_model_edits with manage_allocation steps, operation (add or remove), sourceId, and targetId. No diagram is required. Physical deployment uses Part usages, not their component types. Native Capella eligibility and edit permissions still apply; the operation does not silently transfer an allocation from another source.

Adding an existing pair creates no duplicate. Removing an absent pair makes no change. Results identify the source, target, and allocation, whether a change occurred, and whether the relationship exists afterward. Native synchronization and deletion impacts follow Capella’s preferences. Allocation edits create no diagram views.

The edit profile is required. Each step is one undoable transaction and leaves changes unsaved. A failing step rolls back; earlier successful steps remain applied. Inspect completed results and current relationships before retrying, then review and save in Capella.

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. 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.2. 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 uses successful tool status and returned effects to verify each coherent change, including semantic changes, realization links, and requested diagram content. It inspects again only for a failure, unexpected result, missing evidence, or your explicit request. For transitions, it uses the returned created or reused targets and exposes them 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 edits can remain unsaved; the assistant should report pending changes. Save in Capella after review, or explicitly ask the assistant to save the identified session. sirius_save_session uses Sirius’s native saving policy for the session’s semantic and representation resources, including pending changes made outside the assistant’s task. It requires the edit profile and returns the resulting status: SYNC means synchronized, while DIRTY means changes remain pending. A successful call alone is not proof that the session is synchronized, nor that a Team for Capella commit occurred.

2.5.1. Recover from a Failed Multi-Step Operation

Failure handling depends on the operation:

Operation Failure and recovery

Palette creation, contextual semantic creation, or a batch of element descriptions

Each call is atomic: a reported transaction failure rolls back all its edits. Correct the problem before retrying; do not reuse identifiers from rolled-back work. Dependent creation using new parents or views needs a subsequent call.

Representation management, diagram management, Capella model-edit steps, or EMF edit steps

The batch stops on the first failure; earlier successful steps remain applied. Read the completed and failed step results, inspect only uncertain effects, and resume missing work instead of repeating the whole batch.

Connection loss or an uncertain response

Do not infer rollback from a timeout. Inspect the affected model or diagram before retrying to avoid duplicates.

Individual Functional Chain and allocation steps are undoable transactions, but the enclosing Capella model-edit batch is not atomic. Never bypass a lock or permission failure with a different tool family.

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. Recovery depends on whether the operation is atomic or can retain earlier steps. Follow batch failure and recovery; inspect uncertain effects before retrying to avoid duplicate changes.

3.4. Where can I find changes and known limitations?

4. Help and support

4.1. Self-service resources

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.