Expose Compozy over MCP

Use compozy mcp serve when an external MCP client needs to operate one Compozy workspace through the daemon's existing Host API. The command is a foreground relay: start the daemon first, keep the relay process alive while the client is connected, and stop it when the client no longer needs access.

Serve over stdio

The default transport is stdio. Add a command like this to the MCP client's server configuration, adapting the surrounding JSON shape to that client:

{
  "mcpServers": {
    "compozy-workspace": {
      "command": "compozy",
      "args": ["mcp", "serve", "--workspace", "/absolute/path/to/workspace"]
    }
  }
}

The relay uses the shared CLI context chain: --workspace, COMPOZY_WORKSPACE, validated session identity, then cwd discovery. The flag accepts an ID, name, or path and overrides the inferred workspace. Keep the explicit override in client configuration when the client's launch directory is not stable. The daemon must already be running under the same COMPOZY_HOME as the relay.

Stdio does not add a bearer-token exchange. The local process that starts the command receives the published operator authority for the bound workspace. Stdout carries MCP protocol frames only; diagnostics go to stderr.

Serve over loopback HTTP

Use streamable HTTP when a local client cannot spawn a stdio server:

export COMPOZY_MCP_SERVE_TOKEN='replace-with-a-high-entropy-token'
compozy mcp serve \
  --workspace /absolute/path/to/workspace \
  --transport http \
  --listen 127.0.0.1:3210

Connect the MCP client to http://127.0.0.1:3210/mcp and send the token as Authorization: Bearer <token> on every request.

HTTP startup fails if the listener is not loopback or if the token environment variable is empty. The default variable is COMPOZY_MCP_SERVE_TOKEN; select another variable name with --token-env. There is intentionally no command-line token value or config.toml key, so the credential does not enter process arguments or persistent Compozy configuration.

Understand the published tools

The relay derives schemas from the canonical Host API contracts and publishes tools in the separate compozy_host__<family>__<verb> namespace. Examples include compozy_host__sessions__list and compozy_host__tasks__create. These are MCP façade names, not native compozy__* tools.

The approved families are sessions, workspace-safe task operations, Network, memory, and resources. Target-only task mutations that cannot be bound safely from their request shape are excluded, as are daemon-global and unrelated Host API families. New Host API methods remain unpublished until they receive an explicit projection decision.

The relay resolves the selected workspace once per façade session and injects its canonical identity into every call. A caller cannot replace that identity in tool arguments, and a relay for workspace B cannot list workspace A's sessions or tasks.

Trust boundaries

• compozy mcp serve does not start a second daemon or open runtime databases directly. It relays calls over the active daemon's Unix domain socket and keeps the Host API capability and rate-limit checks in the dispatch path.
• Stdio trusts the local spawning process. HTTP adds bearer authentication but remains loopback-only.
• A workspace binding prevents cross-workspace data access; it does not isolate processes sharing the same operating-system account.
• BackendLocal runs agents directly on the daemon host and is not an isolation boundary. Use a provider-backed sandbox for untrusted execution.
• Secret redaction is defense in depth. Exact protections remain active when the optional heuristic is disabled, but redaction does not replace authorization or sandboxing.

Read the repository Security policy for the canonical trust model and Configuration for the redaction lifecycle.