MCP Reference

1. Purpose

This technical reference is for integrators, advanced users, and maintainers. It describes guidance discovery, server profiles, tool contracts, identifiers, and client diagnostics. It is not an additional agent prompt and is not copied into the modeling workspace.

For modeling sessions and expected assistant behavior, use Working with Capella. For capabilities and the compact tool catalogue, see Features. For connection setup, start with the quick start or the transport examples in the installation guide.

2. Preconditions

  • Configure the aggregate capella-mcp server through stdio or Streamable HTTP.

  • Load its guidance as described below; no local AGENTS.md copy is required.

  • Start Capella only when proceeding to runtime discovery and model operations.

3. Guidance Discovery

The same guidance is available over stdio and HTTP/HTTPS:

Mechanism Content How to retrieve it

Server instructions

Short startup and cross-tool guidance

Delivered in initialize by the current implementation; its use depends on the client.

capella_init prompt

The exact packaged initial instructions

Select the no-argument MCP prompt in a client that exposes prompts.

Operating contract

Capella tool workflows, authorization, recovery, and reporting

resources/read with URI capella://guidance/operating-contract.

Arcadia context

Engineering posture, layers, and relationships

resources/read with URI capella://guidance/arcadia.

capella_get_agent_guidance

Initial instructions and both complete documents

tools/call with no tool arguments when resource reading is unavailable or fails.

The server’s initialization instructions already direct the assistant to load both documents. Both resources advertise annotations.audience: ["assistant"] and annotations.priority: 1.0. These are context-selection hints, not a command to fetch or inject the documents. The MCP Java SDK 1.1.3 supports these fields. See MCP resource annotations.

Resources first is this project’s recommended startup policy, not a protocol requirement. Resources are managed by the host application; tools can be selected by the model. Neither publication nor discovery guarantees that the full document reached the model’s context. See the official MCP resource model.

For conversation startup and the conditional fallback prompt, see Start a Conversation. Guidance loading is an agent workflow expectation; the server does not gate tool calls on a guidance-read flag.

These are MCP resource identifiers, not browser URLs or local file paths. Successful loading requires the contents of both documents from resources/read or the guidance tool. Resource listings and initialization instructions alone do not load the full guidance. After the client’s MCP handshake, the relevant methods and parameters are:

{"method":"resources/list","params":{}}
{"method":"resources/read","params":{"uri":"capella://guidance/operating-contract"}}
{"method":"resources/read","params":{"uri":"capella://guidance/arcadia"}}

If reading is unsupported or fails, discover the guidance tool with tools/list or the client’s tool search, then call:

{"method":"tools/call","params":{"name":"capella_get_agent_guidance","arguments":{}}}

These fragments show MCP methods and parameters, not complete transport requests. The client supplies JSON-RPC IDs, initialization, and HTTP headers where applicable. Client wrappers may prefix tool names with the configured server name. In HTTP mode, resource reads use the configured MCP endpoint, not a separate HTTP path derived from the resource URI.

The tool returns initialInstructions and documents, whose entries contain uri, mimeType, and text. It uses the same packaged Markdown files as the resources. It takes no arguments, makes no runtime connection, and mutates no model state. Its contents and the resources are available in both profiles. Do not fetch the same documents again through the tool after successful resource reads unless the content needs to be refreshed.

3.1. 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 are documented integration routes, not a claim that all product versions have passed a Capella acceptance run. Sources checked on 2026-09-08: OpenAI MCP, Codex project instructions, Claude Code MCP, Claude Code instructions, and Claude Desktop setup. OpenAI recommends keeping the essential server guidance in the first 512 characters; this is a placement recommendation, not a universal MCP size limit.

The capella_init prompt is a user-selected onboarding shortcut. It returns the exact packaged INITIAL_INSTRUCTIONS.md as a user message. It does not load the two extended documents or connect to Capella; follow its resource instructions, then provide the modeling task. In Claude Code, connected MCP prompts appear as /servername:promptname commands. Other clients may expose prompts differently or not at all. See MCP prompts and Claude Code prompt commands.

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

3.3. Protocol Versions

SDK release numbers and dated MCP protocol revisions are different. The current Java SDK 1.1.3 transport implementations advertise 2024-11-05 for stdio and multiple revisions including 2025-06-18 for Streamable HTTP. The client and server negotiate a supported revision; record the actual result in acceptance reports. Resources work in both transports. Aligning protocol revisions or migrating the SDK is separate from guidance delivery.

4. Server Profiles

For Capella work, prefer the aggregate Capella server. It already exposes the three tool families needed by Capella workflows:

  • capella_*: Capella business and Arcadia helpers, including semantic creation when diagram-driven creation is not intended or available

  • sirius_*: runtime, session, representation, diagram, diagram-scoped palette, selection, and read-only AQL helpers

  • emf_describe_model: low-level Sirius-session-backed EMF inspection

  • emf_apply_edits: low-level edit fallback in the edit profile; create_new_element is Ecore-only, while set_properties can edit writable features of existing Capella elements

The --profile option is optional. When omitted, capella-mcp uses the edit profile and publishes all tools, including model-mutating tools. The default stdio launch can therefore be started with the following command from the extracted agent directory. Examples use Windows names; on Linux/macOS, use forward slashes and omit .cmd. See Paths and executable names.

bin\capella-mcp.cmd

Use --profile read-only to restrict the tool surface, or --profile edit to select the default explicitly:

bin\capella-mcp.cmd --profile read-only
bin\capella-mcp.cmd --profile edit

Use the Sirius server only for generic Eclipse/Sirius automation outside a Capella workflow:

bin\sirius-mcp.cmd --profile read-only
bin\sirius-mcp.cmd --profile edit

Profiles filter the tools published by the MCP server:

  • read-only: publishes active inspection tools only; legacy tools are excluded.

  • edit (default when no profile is specified): publishes every tool, including model mutation tools.

Current read-only limitation: The read-only profile excludes tools classified as editing operations, but does not guarantee that model and session data remain unchanged. Some inspection operations can activate viewpoints or open diagram editors, which may modify session or diagram data. AQL runs through the session interpreter, and the profile does not enforce that invoked Java services are free of side effects. Treat this profile as tool filtering, not as protection against all data modifications.

Profiles and agent instructions are complementary. Retrieve the operating contract through resources or the guidance tool, especially when edit exposes mutating tools. Use --profile read-only for the initial installation check.

The server currently publishes 43 tools. The recommended surface contains 32 active tools; 11 legacy logical-analysis tools are deprecated and retained for compatibility. Legacy tools are available only under edit; they are not guaranteed to leave data unchanged. Their functional intent metadata is preserved, but fr.obeo.ai.automation/mutating is conservatively set to true for every deprecated tool. The read-only profile exposes 20 active inspection tools. Legacy-tool metadata and descriptions identify active generic Sirius, impact-analysis, or model-inspection replacements. See features for the complete lifecycle catalogue.

5. Incremental EMF inspection

emf_describe_model is a read-only SIRIUS_EMF tool. Start from the semantic resources of an explicit Sirius session:

{
  "runtimeId": "runtime-1",
  "sessionId": "session-1",
  "steps": [{"kind": "describe_roots"}]
}

Each root includes element (ID, identifier namespace, metaclass and qualified name), name, parent, containmentFeature, and hasChildren. Controlled resource roots retain their actual containment parent. Use a returned semantic ID as a target for the next call:

{
  "runtimeId": "runtime-1",
  "sessionId": "session-1",
  "steps": [{
    "kind": "describe_properties",
    "targets": ["returned-element-id"],
    "featureKind": "containment"
  }]
}

describe_properties returns feature/value pairs. References have kind: "reference" and a referenceValue with the same element metadata as roots; multi-valued references use kind: "list" and listValue. Null and empty references retain null and empty-list values. Referenced elements are not recursively expanded. Each target description also includes its parent.

Optional filters:

  • featureKind: all (default), attributes, references (including containment), or containment.

  • featureNames: exact structural feature names, intersected with featureKind. Omitted or empty selects all names; unknown names are errors. Feature filters apply only to describe_properties and run before values are read.

  • nameContains: case-insensitive referenced-element/root name filter; metaclass: exact referenced-element/root metaclass filter. Both run before description and do not filter attributes. Each call returns all matching roots or reference values. Reference values keep structural-feature order and each reference’s EMF order; roots use resource-URI order and each resource’s root order. Attribute values are unaffected by element filters. Populated reference properties with no matching elements are omitted; genuinely empty/unset properties remain visible. Filtered reference lists are not complete replacements for the original model values.

IDs resolve across the session’s semantic and controlled resources; qualified names are an ambiguity-checked fallback. Non-semantic objects retain handle-local identifiers in the Java API; MCP removes these temporary IDs when the per-call handle closes.

This describes actual EMF containment, not Capella Project Explorer grouping, virtual nodes or Part/component presentation. hasChildren checks immediate containment independently of filters; no complete subtree is returned.

6. Agent Contract Reference

This section explains the routing rules already contained in the AGENTS.md template. It is reference material for client users and maintainers; do not ask the LLM to read it as a second contract. For requesting and reviewing visible changes, see Model Elements and Diagram Content.

Capella and Sirius tools are the preferred modeling path; low-level EMF tools are fallbacks when product-level tools do not express the requested operation.

The agent contract routes tools by the effect required by the request:

  • create content that must appear in a diagram with a palette tool returned by sirius_describe_diagram;

  • inspect sessions and representations with sirius_get_session_details;

  • inspect visible content and available diagram actions with sirius_describe_diagram;

  • inspect architecture-wide Capella context with capella_inspect_model;

  • inspect types, containment, properties, or references with emf_describe_model when no product-level inspection exposes them;

  • use sirius_execute_aql only for a specific missing fact or when the user explicitly requests AQL.

For visible creation, the agent is expected to use this order:

  1. Find or create the intended representation.

  2. Inspect its palette.

  3. Apply the compatible Sirius palette tool.

  4. Verify the resulting view and semantic element.

  5. Prefer a Capella element creation action as fallback when semantic-only creation was requested or the diagram route is unavailable or unsuccessful.

capella_execute_element_creation_action creates a semantic element. It does not create or guarantee a diagram view. Do not create a second semantic element to compensate for a missing view.

For AQL fallback, the agent identifies the missing fact first and queries the most specific known target. It stops when that fact is resolved. One retry is appropriate for an evident expression, type, or selector error; broad model traversal and repeated speculative queries are not the default inspection workflow.

7. Identifier Reference

  • descriptionId: URI of a RepresentationDescription; it selects the type of representation to create.

  • representationDescriptorUid: UID of a DRepresentationDescriptor; it selects an existing representation.

  • diagramHandleId: transient handle for an open diagram editor. Use it only for tools whose contract explicitly requests it.

  • viewId: identifier of visible diagram content; it is not necessarily the semantic element ID.

  • semantic ID or qualified name: selector for a model element. Prefer stable IDs and use qualified names only when unambiguous.

  • expectedDiagramName: safety check for reopening a known LAB instance, not a primary diagram discovery selector.

Session-backed Sirius EMF descriptions and AQL element results return SEMANTIC_ID references. Reuse their id in later element selectors, including after reopening the model handle. Intrinsic IDs are preferred; otherwise the ID is a resource-qualified URI fragment. Positional fragments require unchanged model structure. Resolution is limited to the session’s semantic resources and rejects ambiguous IDs. Standalone model handles remain temporary and are hidden from MCP results. Relationship property values remain strings.

When a LAB view represents a Part, its semantic ID can differ from that of the typed logical component. Use capella_resolve_part_abstract_type before documenting the component shown in the Capella Project Explorer.

8. Realization Mapping Reference

For mapping requests, authorization, and native transition behavior, see Realization Links and Architecture Transitions.

Resolve exact source and target semantic IDs and inspect existing links to avoid duplicates. Use capella_apply_model_edits with attach_realization_link steps and verify the applied links. Similar names alone do not establish realization. The supported mappings are:

Source Target Realization type

Interface

Interface

Logical or context interface realization

Component exchange

Component exchange

Component exchange realization

Communication mean

Component exchange

Component exchange realization

Functional exchange

Functional exchange

Functional exchange realization

Physical link

Physical link

Physical link realization

Physical path

Physical path

Physical path realization

Port or component port

Same port kind

Port realization

Function input/output port

Same port kind

Port realization

Physical port

Physical port

Physical port realization

Physical port

Physical link

Physical link realization

Scenario

Scenario

Scenario realization

Operational capability

Capability

Abstract capability realization

Capability

Capability realization

Abstract capability realization

Capability realization

Capability realization

Abstract capability realization

State, mode, or final state

Same type

Abstract state realization

State transition

State transition

State transition realization

Change or time event

Same type

State event realization

Data type, class, or exchange item

Same type

Information realization

Operational activity

System function

Function realization

System function

Logical function

Function realization

Logical function

Physical function

Function realization

Entity

System component

Component realization

System component

Logical component

Component realization

Logical component

Physical component

Component realization

Physical component

Configuration item

Physical artifact realization

Operational Analysis

System Analysis

Operational Analysis realization

System Analysis

Logical Architecture

System Analysis realization

Logical Architecture

Physical Architecture

Logical Architecture realization

Physical Architecture

EPBS Architecture

Physical Architecture realization

Component Exchange to Functional Exchange allocation is currently unsupported through MCP. emf_apply_edits cannot create Capella metaclasses. Use Capella’s Allocated Functional Exchanges property field for this operation.

When no dedicated mapping applies, the service may use a transformation trace between traceable elements. Verify the returned link and its owning feature after creation.

9. Sirius Palette Selection Tools

Some diagram palette tools ordinarily open a semantic-element selection dialog. For tools returned by sirius_describe_diagram under palette.selectionTools, use this headless workflow instead:

  1. Read the descriptor’s toolName and exact requiredArguments.

  2. Call sirius_list_palette_tool_candidates with that toolName, the target view ID, and the source view ID when required.

  3. Choose only returned candidate id or qualifiedName values. They identify model elements; never substitute a diagram viewId. Respect the returned selectionMode: single-selection requires exactly one value; multi-selection may use an empty list.

  4. Call sirius_apply_palette_tools with the same view context and a selectedElements array. The tool injects the selected semantic elements directly and does not open an SWT dialog.

Selection candidates are revalidated when the edit runs. Do not use alias or newName in selection steps. If the candidate set has changed, rediscover it before retrying.

{
  "representationDescriptorUid": "representation-1",
  "steps": [
    {
      "toolName": "Insert Existing",
      "targetViewId": "root-view",
      "selectedElements": ["semantic-element-id"]
    }
  ]
}

sirius_describe_diagram also returns collaborativeInfo. Its palette is empty when the representation is locked by another user, read-only, or frozen. Refresh a frozen representation and describe it again before choosing a tool. If a stale palette request is rejected while the representation is confirmed as blocked, the failure includes COLLABORATIVE_PERMISSION_DENIED and its collaborative context. Other command rejections only state that Sirius cannot apply the tool to the selected view because an UnexecutableCommand does not identify a failed precondition, an invalid target, or an execution-time semantic lock.

10. Sirius Batch Diagram Tools

The Sirius MCP edit surface now uses two batch tools for representation and diagram work:

  • sirius_manage_representations: ordered, non-transactional representation lifecycle steps for create_representation, open_existing_diagram_by_id, open_existing_diagram_by_name, and close_diagram

  • sirius_manage_diagrams: ordered, non-transactional diagram edit steps for arrange_diagram, refresh_diagram, export_diagram_image, and rename_view_semantic_element

Both tools stop on the first failure and keep earlier successful steps applied. Aliases are supported only by sirius_manage_representations.

Example sirius_manage_representations call:

{
  "sessionId": "session-alpha",
  "steps": [
    {
      "kind": "create_representation",
      "descriptionId": "LAB",
      "semanticTarget": "root",
      "representationName": "Logical Architecture Blank",
      "alias": "lab"
    },
    {
      "kind": "close_diagram",
      "diagramAlias": "lab"
    }
  ]
}

Example sirius_manage_diagrams call:

{
  "sessionId": "session-alpha",
  "representationDescriptorUid": "representation-1",
  "steps": [
    {
      "kind": "arrange_diagram"
    },
    {
      "kind": "export_diagram_image",
      "targetFile": "target/lab.png",
      "format": "png"
    }
  ]
}

11. Qodo IDE Plugin Or VS Code Sees Tools But Tool Calls Fail

If the Qodo IDE plugin or VS Code displays the tools exposed by capella-mcp, the MCP server is reachable through the configured transport. Seeing the tool list confirms that the client can contact capella-mcp; it does not confirm that capella-mcp can discover the running Capella IDE runtime.

Run sirius_list_runtimes first:

  • an empty list means no Capella/Sirius automation runtime is visible from the MCP server process;

  • a runtime entry means discovery works and later failures are more likely approval, token, workspace, project, or stopped-runtime issues.

If discovery reports that stale runtime metadata cannot be cleaned up, run the generic Sirius cleanup command outside the restricted client process:

bin\sirius-cli.cmd runtimes clean

Use bin\sirius-cli.cmd runtimes list to inspect the runtime registry. This command is intentionally not duplicated in capella-cli because Capella uses the same Sirius automation registry.

12. Start a New Discussion

See Start a Conversation for the modeling-session startup and connection check.

13. If Guidance Was Not Loaded

The copyable fallback prompt is now in Working with Capella: If Guidance Was Not Loaded.

14. Expected Agent Behavior

See Inspect the Model, Request Changes, and Review and Save for expected assistant behavior throughout a modeling session.