CLI and MCP

The CLI and local MCP server use the same authenticated API as the dashboard. They manage persistent agents; com agent login, status and logout configure a model provider for local runs and are a separate feature.

Use the CLI

Install and sign in, or update an existing installation with com update (npm update -g @composal/cli for npm installations). Check your installed command help before scripting. Older releases may expose only local-provider commands under com agent.

com agent --help
com agent list --org acme --json
com agent show AGENT --org acme --json

AGENT is the readable url_slug, legacy slug or returned agent_… public ID. Organization selection is explicit here; commands can also use your saved organization context. Keep token values in the CLI's saved authentication or COMPOSAL_API_TOKEN, not --api-token arguments.

Configure and control an agent

Configuration, lifecycle and message mutations take an exact JSON request file and an idempotency key. Use the API guide to prepare create-agent.json, activate-agent.json and message.json, including the expected versions. The same files work through either surface.

com agent create --org acme --body-file create-agent.json \
  --idempotency-key research-agent-create-001 --json
com agent show AGENT --org acme --json
com agent activate AGENT --org acme --body-file activate-agent.json \
  --idempotency-key research-agent-activate-001 --json
com agent message AGENT --org acme --body-file message.json \
  --idempotency-key research-message-001 --json
com agent updates AGENT --org acme --json

Read setup_pending after creation and wait for private state setup. Use update to save {expected_version, configuration}; activate the new revision to use it for new work. pause, resume and archive take a file containing {expected_version} from the latest lifecycle snapshot. Run com agent COMMAND --help for the exact flags supported by your release.

Use stop with {task_id, expected_version} to stop a particular task; take the expected version from a current conversation snapshot. Pausing the agent and stopping one task are separate controls.

updates reads durable outcomes; message acceptance alone is not a reply. Pass --before with the returned next_before to inspect older outcomes. mark-read AGENT --sequence N acknowledges displayed outcomes for your user. For live message/task status, use the conversation API.

Keep the body file, key and expected versions unchanged after a timeout. If you deliberately change the request after resolving a conflict, give that new operation a new key.

Share an agent

New agents default to organization sharing. In a CLI release with com agent share, echo sharing_version from show:

com agent share AGENT --org acme --visibility organization --expected-version 7 --json

Use --visibility private to restrict the audience. This command uses optimistic version checking rather than an idempotency key. After an uncertain response, run show to confirm sharing before retrying. Members can view and message a shared agent; owners and explicit managers control settings. Existing agents also become organization-shared at rollout; owners/managers can switch them to private afterward. If your installed CLI does not include share, use the sharing API.

Use an MCP client

Install the local Composal MCP server into a supported client:

com mcp init --help

Follow its interactive target selection, or use com mcp stdio as the server command in your client's MCP configuration. Sign in with com login first. The server's com_command tool accepts the same arguments you would type after com:

{"args":["agent","list","--org","acme","--json"]}

To send an existing exact request file:

{
  "args":["agent","message","AGENT","--org","acme",
          "--body-file","/absolute/path/message.json",
          "--idempotency-key","research-message-001","--json"],
  "cwd":"/absolute/path/to/project"
}

Use the same tool for show, create, update, activation/lifecycle actions, and updates. The MCP tool returns ok, exit_code, stdout and stderr; inspect the JSON response inside stdout and check errors before continuing. It runs with closed stdin, so MCP mutations need a real body file rather than --body-file -. Never put API tokens or provider secrets in tool arguments.

Understand account and connector scope

The local MCP server uses the signed-in Composal user and organization context. It preserves the API's agent sharing, management authorization and version checks. Installing it does not connect an app account to a persistent agent: select that account separately in the agent's Settings.

The remote Verify MCP connector is scoped to verification. Do not use its Verify OAuth token to manage persistent agents. Use local com_command for MCP management, or the HTTP API with a personal access token for a server integration.