Connect an external agent

Use the Ennea plugin for a supported assistant host, or the private developer CLI supplied with your Ennea checkout/package. Both use the access levels in External agents. Start with Read and select the exact workspace and entity types you need.

Install Ennea for Codex

The public Ennea plugin project provides the marketplace package; access to Ennea's application repository is unnecessary. In a host with the Codex plugin CLI, install it with:

codex plugin marketplace add AlaaSubora/ennea-codex-plugin --ref main
codex plugin add ennea@ennea

1. Restart the desktop host after installation and start a new chat with Ennea enabled.
2. Use the host's Ennea connection control. Sign in through Ennea's browser flow and choose organization, site, environment, access level and permitted record types.
3. Run the plugin's Setup skill. Expect ennea_context and ennea_capabilities to return the actual connected identity/workspace and available operations.
4. Ask for a read-only list of up to ten permitted Materials. Check its scope and sources before requesting changes.

The hosted service is https://api.ennea-ai.com/mcp; use your supplied endpoint for a different deployment. The host manages OAuth credentials. You do not need a token in chat or a local MCP process for this plugin path.

For marketplace setup and host-specific installation, see OpenAI’s plugin packaging guidance. Use a client version that supports the shown commands.

Developer CLI from a private checkout

The adapter package is private and is not a public npm download. Obtain the reviewed source checkout or release archive from your implementation contact. For a checkout, use Node.js 24 and pnpm:

pnpm install
pnpm --filter @ennea/agent-adapter cli --help

Create a bounded developer credential under Operations Studio → Integrations → AI agents → Agent access. Choose Read, your Test workspace and Material if available. Store the credential in a private file using your approved credential process. Set its path and the API origin; the examples below contain no token:

export ENNEA_URL="https://api.ennea-ai.com"
export ENNEA_TOKEN_FILE="/absolute/private/path/ennea-token"
pnpm --filter @ennea/agent-adapter cli context
pnpm --filter @ennea/agent-adapter cli capabilities material
pnpm --filter @ennea/agent-adapter cli query --file /absolute/path/agent-query.json

Download agent-query.json before the last command. It contains:

{ "entityType": "material", "limit": 10 }

The file is read-only input. context must show the intended connection scope, capabilities material describes currently permitted actions and schemas, and query returns accessible Material results up to the requested limit. Zero results can be valid; inspect scope/access before assuming data is missing.

CLI output is one JSON object. Exit 0 means the command completed; 1 means input/transport failed before a structured result; 2 means the returned result needs attention. Read the returned safe error code. Do not interpret an attention result as successful publication or execution.

Move from reads to a draft

Reconnect or issue a separate credential with Draft editor only when drafting is intended and authorized. Read the target draft and its exact expectedVersion, edit it using the discovered schema, and inspect the saved draft in Studio. A separate explicit publication requires Publisher, the person's current native rights and the exact current version. Use External agents for operations, batches and durable receipts.

Connection recovery

Symptom	Action
Plugin visible but tools unavailable	Enable Ennea, refresh marketplace package, restart the host and test a new chat.
HTTP 401 / Auth required	Reconnect through the host, or check the CLI credential expiry and issuing session.
Action/entity forbidden	Check consented level/types and current native rights.
Wrong workspace	Reconnect with the intended scope; changing tool arguments cannot change it.
Write result unknown	Inspect the original operation receipt; retain its invocation/idempotency identity.

Refresh tokens rotate; the connection remains bound to its issuing session, expiry and current rights. Revoking it stops future access and preserves completed records/history. See support for safe evidence to provide.