Breyta MCP Flow Authoring

Authoring through MCP stays draft-scoped until a user explicitly approves release or publishing.

Recommended workflow:

Read breyta://mcp-docs/overview and this document.
Get prompt create_flow_from_goal when the user is asking for a new flow.
Use search_flows for examples and nearby workspace flows.
Call list_connections and check_connections before designing steps that depend on external systems.
Call get_step_reference for the exact primitive you plan to use.
When editing an existing flow, call get_flow_definition for the exact source: draft for current authoring state, live for released behavior, or omit source and pass version for a specific released version.
Read focused flow language docs only when needed; do not load the full CLI docs into context by default.
Draft or edit an EDN flow_literal.
Call validate_flow_definition with the flow_literal.
Call create_flow_draft only after validation errors are understood.
Call check_flow_readiness before running setup-sensitive drafts.
Run a draft invocation through a flow MCP interface or existing run tooling.
Use inspect_run_step when a run fails or a step output shape is unclear.
After explicit user approval, call release_flow to release/promote the selected version to live.
Pull get_flow_definition with source: "live" and smoke-test the live or install-shaped path before calling the work released.
Keep publish, billing, and setup mutation behind explicit user approval and non-MCP workflows unless a supported MCP tool exists.

MCP docs are not CLI transcripts. They should describe MCP tool calls, required arguments, resource URIs, safety checks, and the next MCP action an agent should take.

create_flow_draft accepts a supplied EDN flow literal. It does not generate a flow from a goal server-side and does not release or publish.

validate_flow_definition accepts either a supplied EDN flow literal or an existing flow_slug plus source/mode. It returns diagnostics without publishing.

get_flow_definition pulls the full source literal for draft, latest,
live/active, or a specific version. Use source for named source reads,
or omit source and pass version for a specific released version. Use it
before modifying an existing flow and again after release when you need to
confirm the live definition. The response includes the editable source as the
top-level flowLiteral.

release_flow releases the supplied version, or the latest pushed version
when version is omitted, and promotes it to the workspace live target. It is
in the release toolset, requires flows.manage, and should only be called
after the user approves the specific flow and version. It does not accept deploy
keys; deploy-key-guarded flows should be released through an operator workflow
that can handle the secret outside MCP context.

MCP Authoring Contract

Use this shape for agent-authored work:

Stage	MCP primitive	Expected behavior
Discover	`resources/list`, `prompts/list`, `search_flows`	Gather only the context needed for the task.
Inventory setup	`list_connections`, `check_connections`	Reuse existing workspace connections and catch missing credentials before authoring around them.
Inspect primitive	`get_step_reference`	Fetch exact step docs/examples for the primitive being used.
Draft	local reasoning plus `flow_literal`	Produce a complete EDN flow definition with explicit `:slug`, `:name`, `:concurrency`, `:invocations`, and appropriate `:interfaces`.
Validate	`validate_flow_definition`	Fix diagnostics before creating or updating a draft.
Pull definition	`get_flow_definition`, `breyta://flows/{slug}/definition/{source}`, `breyta://flows/{slug}/versions/{version}/definition`	Pull exact draft/live/latest or versioned source before editing, reviewing, or debugging definition drift.
Save draft	`create_flow_draft`	Write draft state only. Do not release or publish.
Check setup	`check_flow_readiness`	Run existing doctor, configuration, and preflight checks before claiming readiness.
Exercise	`inspect_flow_tool`, `call_flow_tool`, `get_run_status`, `inspect_run_step`	Prefer draft/source-specific testing and focused step inspection when the user is still iterating.
Release	`release_flow`	Release/promote only after explicit user approval, then verify live definition and behavior.
Report friction	`send_feedback`	Send redacted docs/runtime/interface feedback when the MCP path is unclear or blocked.

Authoring Rules For Flow MCP Interfaces

When a flow is meant to be reusable by other agents, expose a small
:interfaces :mcp surface over a clear invocation contract:

Give each MCP tool a stable :tool-name in the flow definition; call it through MCP as tool_name.
A flow may expose multiple MCP tools when they are related operations on the same solution; keep tool names unique.
Keep per-run arguments in :invocations, not in :requires.
Use invocation input :type :json for object or array payloads that agents pass through call_flow_tool as input.
Put one-time setup, connections, secrets, and installer-owned config in :requires.
Write tool descriptions for humans and search. They are hidden from agents by default.
Prefer structured output and resource refs over large inline blobs.
Make destructive or externally visible actions explicit in the tool name and description.
Validate and smoke-test the draft before claiming that the MCP interface is usable.

Use search_flow_tools after saving a draft or release to verify the interface
is discoverable through the workspace MCP server. Discovery is a lookup step;
call_flow_tool still re-checks the selected flow interface before starting a
run.

Context Budget

MCP clients work best when they do progressive discovery. Start with the MCP
docs resources and targeted search_flows/search_flow_tools calls, then read
specific flow resources or reference docs as needed. Avoid stuffing full flow
definitions, long run logs, or broad CLI docs into every tool call.

Approval Boundaries

create_flow_draft writes draft state. release_flow can release/promote a
flow to live when the server entry either exposes the release toolset or does
not narrow toolsets, and the token has flows.manage. Treat release_flow as
an approval-gated action: show the flow slug, selected version, release note,
and any readiness risks before calling it.

Publish, marketplace visibility, paid billing, secret changes, setup mutation,
replay, cancellation, and wait approval remain outside this MCP surface. Use
existing Breyta approval and operator workflows for those actions.