How the server connects to Enterprise Architect
The server does not embed or replace EA. It attaches to the EA application you already have open and acts on whichever project is open in it. The module that does this is described in Inside the server.
How the server finds EA
On the first call that needs EA, the server:
- Reuses its existing connection to EA if there is one and it is still live. It tests this by reading a cheap property of the repository. If the test fails, the connection is stale. The server drops it and reconnects.
- Otherwise attaches to the running EA instance through Windows' registry of running automation objects.
- Reads the repository from the application and keeps both.
If you name a project file with open_project, the server compares it with the open project and opens the file if it differs.
When EA is not running
The server does not start EA. If it finds no running instance, the call fails with ea_not_running and names launch_ea as the remedy. Starting an application on someone's desktop is your decision, so the assistant is expected to ask. With your agreement, launch_ea starts EA and waits up to 30 seconds for it to become responsive. If EA does not respond in that time, the call fails with an error.
That is a limit of the server, not of AI Power Tools. Where computer use is available, the assistant can start EA the way you would, open the model, and tell you what EA's window shows. Where it is not, it asks you to start EA and open the model.
The safest sequence: start EA yourself and open a project, or have the assistant call get_repository_info first and call launch_ea only when it reports that EA is not running.
When no project is open
If EA is running but no model is open, the call fails with ea_no_model_open and names the remedies.
| Operation | What it does |
|---|---|
open_model |
Opens an existing .qea, .qeax, .eap or .eapx file in the running EA |
open_project |
Opens a project file. If a different project is open, EA closes it first. Returns the resulting connection |
create_model |
Creates a new SQLite-backed .qea file (the suffix is added if missing) and opens it |
close_project |
Closes the open project without exiting EA |
Each fails with an error if EA refuses to open or create the file. Where computer use is available, the assistant can also open a model through EA's own window. Opening a model through EA's automation interface is slow. Expect 5 to 15 seconds, toward the top of that range.
One EA instance
- The server attaches to one instance. If several EA windows or processes are open, it attaches to whichever Windows returns, in practice the one that registered first. To target a specific instance, close the others before the server starts.
- Never start a second EA against the same model file. It is a genuine way to corrupt work. A per-user Sparx license also limits concurrency to one instance per seat. A per-user seat may run on a server or virtual machine, with concurrency still capped at one.
- One Claude Desktop extension serves Claude Desktop chat, Claude Cowork and the Code tab, so they share one server and one EA. Claude Code in a terminal does not load Desktop extensions and does not reach EA through this server (Supported clients).
What the server does not change
It does not close or exit EA, does not save on your behalf beyond what each operation does, and does not select a project for you when several exist. Always check which project is open: get_repository_info returns the project path. When the repository has user security enabled, it also returns whether security is on and who is logged in.
Latency and blocking dialogs
EA is single-threaded. A slow operation blocks its interface and everything queued behind it.
| Operation | Typical wait |
|---|---|
Opening a model (open_model, open_project) |
5 to 15 seconds, toward the top |
launch_ea |
Up to 30 seconds before the call gives up |
| Importing or deploying an MDG Technology | 3 to 8 seconds |
execute_sql when no dialog is expected |
1 to 3 seconds |
| Any call that may open a dialog | 3 to 5 seconds |
- "(Not Responding)" in EA's title bar means EA is processing, not that it crashed. Wait. Do not re-issue the command, double-click or open a second instance. During file and import operations it is normal.
- A modal dialog blocks every later call. EA reports many failures as a modal dialog that waits for a person, for example when it cannot parse a query. The server guards the known causes. It checks column names against EA's schema before sending a query, it refuses
add_imageon repositories it cannot write the right database dialect for (Supported repositories), and it avoids functions the SQLite engine lacks. The server cannot see or dismiss a dialog. If calls hang, a dialog is likely open on the EA desktop. COM error0x800401E3("Operation unavailable") has the same cause. If it persists after the dialog is dismissed, restart EA. max_rowsonexecute_sqlshrinks the response, not the work. EA runs the whole query and the cap applies after EA returns. To make a query cheaper, put the database's ownLIMITorTOPin the query.