The AI Power Tools MCP Server for Sparx EA

ea-mcp-server.exe is the AI Power Tools MCP Server for Sparx EA: a Windows console program that exchanges requests and results with the AI client over standard input and output and drives EA through its automation interface. It announces itself to the client as AI-Power-Tools-for-Sparx-EA.

What it is

• Compiled, not interpreted. Release builds are compiled to native code, so no Python is needed on your machine. The build is a folder holding the program and the libraries it needs, packed into the Claude Desktop extension and the VS Code extension.
• Signed. Every program file and library in the package is signed under the NovoCircle publisher with Microsoft's code-signing service, and the signature is checked again inside the finished archive. A build that cannot be signed cannot be published. Signing every file individually is what avoids the Windows Defender false alarms that unsigned libraries trigger.
• No listener. It opens no network port and cannot be reached by other machines.
• Its version is reported by ping and by the update check.

Tools it offers

Seven tools. Six grouped tools dispatch to named operations, and ping is a health check.

That is 149 operations in total. MCP server: tools and operations documents each one.

How the server checks a call

Before any call reaches EA, the server checks it in order and returns a structured failure for the first check that fails. The assistant reads the failure and corrects the call.

1. The operation name must be a plain name. A name written as a function call is rejected.
2. The name must be an operation of that tool. An unknown name is rejected, with the list of valid operations.
3. Read-only mode must not block it. A blocked call returns readonly_mode.
4. Every argument must be one the operation accepts. An unknown argument returns unknown_parameters, naming the offenders, what the operation accepts and a close match.
5. Every required argument must be present. Otherwise the call returns missing_required_params.

Two EA-state failures come from a wrapper around every tool except ping: ea_not_running, which names launch_ea as the remedy, and ea_no_model_open, which names open_model and create_model. The error code and the remedy are the contract. Troubleshooting lists the codes you may meet.

Lifecycle

1. Start. The AI client launches the program: Claude from the Claude Desktop extension, VS Code from its registration of the VS Code extension. The process is named ea-mcp-server.
2. Initialize. It sets up logging, notes whether diagnostics are on, and answers the client's initialize and tools/list requests. The two background checks for updates start only after the client has its initialize reply (see below).
3. Serve. It answers requests. It does not contact EA at startup. The first call that needs EA attaches to it (How the server connects to Enterprise Architect).
4. Stay resident. The process lives as long as the client keeps it. It holds its connection to EA between calls and re-attaches if the connection goes stale.
5. Stop. The server stops when the client closes the connection or stops the process. Stopping the server does not close EA or the open model. A reporting refresh runs inside the server process, and the server keeps its runs in memory: keep the server running until a refresh finishes, because after a restart it does not recognize the run id of a refresh started before it.

While it runs, the process holds a Windows file lock on its own program. That is why a Desktop-extension upgrade must disable the extension first (Updating and uninstalling).

EA is a single-threaded desktop application, so a slow EA operation blocks everything behind it. See How the server connects to Enterprise Architect.

What the server writes to disk

It keeps almost nothing.

Background update checks

Two checks run in the background at every server start. They begin after the client has its initialize reply, so they never delay the connection: Claude Desktop waits ten seconds for all of its local servers and starts the session without any that are late. Until a check finishes, ping and get_repository_info report it as not checked yet. A failed check is silent.

Update check. It fetches the latest release from the public releases page on GitHub, compares its version with the running one, and caches the result. A result less than 24 hours old is not refreshed. The result appears in two places:

• get_repository_info includes an update notice when a newer release exists (update_check reads "not checked yet" until the check finishes and "unavailable" if it ended without reaching GitHub, and skills_update_check does the same for the skills check), with the current and latest versions, the download address, the release notes, how AI Power Tools was installed, and the upgrade steps for that package.
• check_for_updates returns the cached result. Called with force, it starts a fresh check and returns immediately. The fresh result arrives on the next call.

The server tells how it was installed from where its own program sits on disk. The upgrade steps it gives depend on the answer:

A server launched by another client from an unrecognized location is therefore reported as not recognized and never as the Claude Desktop extension. The server never downloads or installs anything by itself.

The notice from ping. The ea-start-here skill opens every session by calling ping with the release the skills were stamped with. The reply carries an update summary (the server's version, the latest release the check found, and whether the server or the skills are behind) and, only when something is behind, a notice that the skill shows you word for word. The current release is the newest of the server's own version, the latest published release and the skills version, so skills that are newer than the server are caught without the network. ping never waits for the release check. While the check is running, latest_version is empty and the update summary carries release_check with the value "not checked yet"; call ping again for the result. If the check could not reach GitHub, release_check says "unavailable". Skills that send no version are not compared.

• Skills behind: "Your AI Power Tools skills are X; the current release is Y. Open https://claude.ai/customize/plugins, choose Manage marketplaces, and sync novocircle. Then quit Claude Desktop completely and reopen it."
• Server behind: "AI Power Tools for Sparx EA X is installed; Y is available.", followed by the upgrade steps for the install route in the table above.

The first tool response after the release check has finished also carries the server-behind notice once, when a newer server release exists, unless ping has already answered.

Skills check. The comparison of the skills against the release manifest depends on whether the server finds the plugin installed. It finds the plugin when it runs from the plugin cache, or when Claude's plugin register (installed_plugins.json in %USERPROFILE%\.claude\plugins) lists the plugin and does not mark it orphaned:

• Where the plugin is found installed. The plugin carries the skills, so the check fetches nothing and stays silent about updates. It reports only copies the older skills installer left in %USERPROFILE%\.claude\skills, as named in that installer's own record. Those copies load a second time beside the plugin's. When there are any, get_repository_info lists them as legacy copies and names migrate-to-plugin.ps1 as the remedy (Moving from an older installation). The list is read fresh at each call, so it shrinks as you remove copies.
• Where the server is the Claude Desktop extension and the plugin is not found installed. Claude Desktop keeps plugins installed on a claude.ai account in a store the server cannot read, so this is the usual case for an account install, and the skills come from that plugin. The check fetches nothing and never recommends install_skills, which would copy every skill into %USERPROFILE%\.claude\skills and load each one twice. What get_repository_info reports depends on what is in that folder and what the assistant reports through ping. With copies the older installer left there, it lists them as legacy copies. Those copies load a second time beside the plugin's skills in the Code tab; Claude Desktop chat and Claude Cowork do not read that folder. It says to add the plugin on your claude.ai account if it is not there yet, and to remove the copies with migrate-to-plugin.ps1, or by asking for prune_legacy_skills to apply with plugin_confirmed once you confirm the plugin is installed on your account. On the extension that confirmation is enough, whether or not the assistant has reported a skills release (Skills (legacy)). With no copies and no skills release reported through ping, it gives one pointer to where the skills come from: open claude.ai/customize/plugins, choose Add marketplace, enter NovoCircle/ai-power-tools-skills, install AI Power Tools, then quit Claude Desktop completely and reopen it. With no copies and a skills release reported through ping, it reports nothing.
• Where the server runs from another location and the plugin is not found installed. The check fetches the skills repository's release manifest and compares it with %USERPROFILE%\.claude\skills. When it finds updates, conflicts or missing skills there, get_repository_info includes a skills notice that names install_skills as the way to apply them. The comparison looks only at that folder, so a skill that Claude loads from a plugin on your account does not count as present.
• Where the server runs from another location and the skills version reported through ping shows the plugin may be in use. If the release the assistant reports is one that no copy in the skills folders can have produced, get_repository_info lists the copies the older installer wrote, with a conditional note: if you installed the plugin from your claude.ai account, those copies duplicate its skills. This is a hint, not proof, because skills can also come from a project's own .claude\skills folder. It does not stop install_skills, and nothing is removed unless you say you installed the plugin on your claude.ai account and ask for prune_legacy_skills to apply with plugin_confirmed (Skills (legacy)).

Neither check sends anything beyond a standard secure web request that identifies the server and its version. No setting turns either check off. Two environment settings redirect them (see below).

Logging and diagnostics

Logging. The server writes its own log lines at the level set by EA_MCP_LOG_LEVEL (INFO by default) to its standard error stream, which the client captures. Where the client keeps that stream depends on the client.

Where each package sets the log level, diagnostics and read-only mode. Each package that carries the server sets the server's environment itself, and they differ. The plugin carries no server and has no settings.

Call history. Every call except ping is timed and recorded in memory, with its outcome, in a buffer of the last 25 calls. Nothing is written to disk by this.

Diagnostic reports (opt-in). With diagnostics on, a call that raises an exception, returns a structured error, or takes at least the slow-call threshold (30 seconds by default) writes a self-contained Markdown report named for the time and the tool. The call's response then also points to the report and to help@novocircle.com. A report holds:

• a summary of the failure
• the environment: server version, operating system, EA version, repository type and project path
• the call's arguments and result, with any value over 500 characters shortened
• the error trace, if there was an exception
• the last 25 calls
• the server's uptime and counts

Review a report, remove anything you do not want to share, and email it to help@novocircle.com. Nothing is sent automatically. Element and package names appear in full. get_repository_info shows the resolved diagnostics settings, so you can confirm the mode without restarting.

Read-only mode

Read-only mode is an administrator control for giving people the tools without write access. When it is on, an operation that modifies the repository returns readonly_mode, with a message naming the operation. Queries and every read operation keep working, and execute_sql still runs, with writes forced off.

In the Claude Desktop extension, turn on Read-only mode on the extension's Configure screen; it is off by default. The setting sets the environment variable EA_MCP_READONLY, which the server reads once at start, so a change takes effect when the extension restarts the server. The VS Code extension has no setting for it. Where a client launches the server some other way, set EA_MCP_READONLY to 1, true, yes or on in the server's environment; whether a system-wide Windows environment variable reaches the server depends on the client and is not confirmed. Test that a write is refused before you rely on it.

Which operations count as writes. The server decides by operation name. An operation is blocked when its name starts with create_, update_, delete_, set_, add_, move_, duplicate_, apply_, import_, install_ or write_. A few others are named individually and blocked too: execute_sql when it is a write, layout_diagram, remove_element_from_diagram, clear_element_image, and the reporting operations build_business_layer and remove_business_layer, which are blocked whichever database their profile names. start_reporting_refresh is blocked only when its profile builds views in the EA repository's database. build_reporting_database and replay_reporting_database are not blocked, because they write a separate database or files, not the repository. Three skill-management operations (install_skills, prune_legacy_skills, resolve_skill_conflict) are exempt, because they write files on disk, not to the repository.

Diagram layout operations are blocked by name too. An operation that changes a diagram but has none of those name patterns is listed individually. That covers layout_diagram, remove_element_from_diagram, the tidy operations neaten_diagram_objects and resize_diagram_objects, and collapse_parallel_connectors and expand_parallel_connectors; a collapse dry run is refused as well. Operations that write files outside the repository, such as exports and generate_report, are not blocked, except write_mdg_xml. Treat read-only mode as a guard against accidental changes, not as a security boundary, until you have tested it against the operations you care about.

Environment settings

The server reads its settings from its process environment once, at start. A change needs a server restart.

Where each package sets the log level, diagnostics and read-only mode is in Logging and diagnostics and Read-only mode. No package exposes the other variables below as settings.

If an optional Desktop-extension setting is left blank, the host can leave literal template text in the variable. The server recognizes that and treats the variable as unset.