engine9 plugin install

Plugins are first-class on a connected engine9 MCP server. Installing a package onto accounts is a native plugin tool call, not a worker task and not local PluginWorker / e9 pluginworker. Use this skill for deploy, listAvailable, settings catalog, and setSetting. Use create-engine9-plugin when authoring or versioning a package (including third-party packages such as acme-plugins).

Quick reference

Rule: Prefer MCP plugin. Never schedule PluginWorker.install via MCP task. Never invent paths from local plugins/ or schemas/.

Rule: listAvailable is the installable catalog for the connected server. If the path is absent, stop and report it — do not read workspace packages as a workaround. For third-party paths (e.g. acme-plugins/loyalty), the host must already npm install that package and list it in engine9.pluginPackages, then redeploy; otherwise it will never appear in the catalog.

Concepts

plugin install writes a plugin row (and schema / settings) into that account's warehouse. There is no bulk-install RPC: one MCP call per account_id. Account search stays one call.

The version of code that runs is the host’s npm package pin (e.g. acme-plugins@1.4.0), not a per-account plugin version. Install does not choose a version; it applies whatever the host has loaded. Dependency failures name the host package version. See create-engine9-plugin — Creating and versioning (Acme).

Unique packages (metadata.unique, typical @engine9/plugins/* and most @engine9/schemas/*) reuse the existing row. Reinstall is idempotent for that path. Third-party packages often default to non-unique unless they set metadata.unique: true.

Declared settings are inserted on first install only. Changing a value later is setSetting, not reinstall. Marketplace auth_fields are not settings.

Workflow

Copy this checklist:

- [ ] mcp_auth → user
- [ ] listAvailable once; resolve path
- [ ] Resolve account ids (one id, or account search)
- [ ] plugin install per account_id (parallel batches)
- [ ] Verify with one account search (plugins filter)

1. Log in

Follow e9-mcp Step 0. If user already succeeded this session, skip.

2. Resolve the package path

Call plugin listAvailable with any account_id the user can access (session id, parent, or a child). Catalog is server-wide.

{ "command": "listAvailable", "account_id": "<account_id>" }

Match the user's string to a returned path (exact, or add @ / treat as suffix). If nothing matches, stop.

3. Resolve target accounts

Rule: Discover ids only via MCP user / account search. If count is 0, stop. Do not resolve the account by any other mechanism: no second search, no accounts.d, account-config.json, frakture-account-config.json, or e9 CLI.

Do not call account plugins (or any other per-child DB probe) before install. Install does not need the method catalog.

4. Install

For each target account_id:

{
  "command": "install",
  "account_id": "<account_id>",
  "path": "@engine9/plugins/models/deployment/v2026_09_16"
}

Run in parallel batches of about 10. Success looks like { ok: true, command: "install", result: { id, path, name, deployedVersion, tablePrefix, included } }.

Rule: Fleet install is the exception to the global MCP "stop on first isError" rule. A per-account Cannot connect / Not authorized / unmet dependencies is a skip for that id. Continue the remaining accounts. Session-level auth failure and getPluginMetadata is not a function still stop the whole job. Report a success/fail table at the end.

5. Verify

One account search — do not fan out command: plugins:

{
  "command": "search",
  "parents": ["<parent_account_id>"],
  "plugins": ["models/deployment/v2026_09_16"],
  "limit": 500,
  "max_scan": 500
}

count should equal the child list. matched_plugins should include the installed path. Retry only the missing ids.

/e9 plugin commands

After e9-cli login:

Natural language ("install <path> on all <parent> clients") is the same workflow without requiring /e9a first: search, then install.

Rules

Rule: Native MCP plugin only. Do not use task, local PluginWorker, or e9 pluginworker when the connected server exposes plugin.

Rule: Do not load create-engine9-plugin for an install request.

Rule: Do not call account plugins once per child to decide whether to install. Unique-path reinstall is safe; verify afterward with one search.

Rule: listAvailable missing the path means it is not installable on this server. Local checkout of the package is not sufficient.

Troubleshooting

Related documentation

• MCP tools
• PII-free accounts (exclude_pii)
• CLI / account scope
• Author a plugin or schema plugin
• Plugin settings authoring
• Add custom fields to a pull