Invoking Flows

A flow is callable identically from a human, from a script, and from an AI agent. All three paths share the same typed signature and return the same shape.

From the zen CLI

The zen CLI forwards to a configured server or a local installation:

zen invoke-flow hello -p message="Hi there"

See The zen CLI for the full command surface.

From any HTTP client

A POST to the flow’s invocation endpoint. live is the branch alias that resolves to production on Git-disabled installs:

curl -X POST http://localhost:5000/api/v1/live/flows/hello/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"Hi there"}'

On a Git-enabled install, replace live with your branch name (e.g. main, staging). The full URL family rules are in API Surfaces.

From an MCP-aware assistant

MCP — the Model Context Protocol — is the open standard AI assistants use to discover and invoke tools. From Claude Code, VS Code, or any MCP client, call the invoke-flow tool:

{ "flow": "hello", "parameters": { "message": "Hi there" } }

The assistant sees the flow’s typed signature through the same metadata the type provider uses, so it can autocomplete the parameters. The same MCP channel reaches read-entity, list-entities, and the operator catalog, so an assistant can run small experiments against your installation as part of diagnosing a problem.

The same shape, every path

All three return:

{
  "echo": "Parameters received successfully",
  "message": "Hi there"
}

That equivalence is on purpose: the typed output: contract is what makes a flow callable from REST, MCP, the CLI, and other flows with the same guarantees.

Reading invocation results and logs

Each invocation gets its own UUIDv7 ID, its own log stream, and its own output. Read them after the fact:

• CLI: zen logs <invocation-id> (supports live tailing).
• REST: the invocations verbs under /api/v1/{branch}/invocations.
• MCP: read-entity entity=invocation and the invocations:///introspection read resource.

Invocations are independent and can run in parallel.