# CLI and MCP

Control persistent agents from the com CLI and local MCP server using the same organization-scoped lifecycle and messaging API.

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](/docs/quickstart), 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`.

```sh
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](/docs/persistent-agents/api#first-request) to prepare `create-agent.json`, `activate-agent.json` and `message.json`, including the expected versions. The same files work through either surface.

```sh
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](/docs/persistent-agents/api#conversation). 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](/docs/persistent-agents/api#conversation).

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`:

```sh
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](/docs/persistent-agents/api#sharing).

## Use an MCP client

Install the local Composal MCP server into a supported client:

```sh
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`:

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

To send an existing exact request file:

```json
{
  "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](/docs/verification#remote-mcp) 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](/docs/persistent-agents/api) with a personal access token for a server integration.