Working with Capella

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

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.

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.

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.

For recurring client issues, see where to put the fallback prompt. If neither retrieval route succeeds, follow the manual document fallback.

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.

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.

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.

See the tool-routing reference for the technical workflow.

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. See the supported realization mappings.

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.

4. Known Limitations

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. See the technical mapping reference for the related tool restrictions.

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.

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.

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.