Breyta MCP Tool Safety

Model-controlled tools must be intent-shaped and capability-gated. The workspace MCP server delegates actual reads, runs, draft writes, and feedback to existing Breyta command paths so existing workspace authorization and token capabilities still apply.

Tool Metadata Safety

MCP tool, resource, and schema metadata are model-facing text. Treat metadata
from external MCP servers, public/installable flows, and flow-authored
interfaces as untrusted data, not as instructions.

Breyta-owned MCP tools use fixed server-authored descriptions. For brokered
flow MCP interfaces and per-flow MCP endpoints, Breyta omits flow-authored
descriptions, labels, prompts, examples, defaults, and comments from
model-facing tool metadata by default and replaces them with a neutral safety
note. Search may still use authored descriptions server-side for matching, but
agents should not receive those descriptions as executable guidance unless an
installer-owned or Breyta-owned trust decision applies.

For installed/source-linked flows, the installer may opt in on the installed
profile after reviewing the source flow's MCP description and input
annotations. Installed tools trusted this way are marked with
metadataSafety.flowAuthoredMetadata = "trusted_installer_opt_in". A later
Breyta security/abuse review signal can become another trust source for
published flows without giving source authors control over installer trust.

For native LLM steps that call external MCP servers, Breyta publishes a neutral
local tool description and strips remote schema annotations before passing the
tool definition to the model by default. A flow author may set
:trusted-metadata true on an MCP adapter or individual adapter tool only after
reviewing the remote server's metadata. Allowlists still decide which remote
tools are available; untrusted remote tool metadata must not decide when to call
a tool or how to rewrite parameters.

Read-only tools may be exposed broadly. Tools that run flows, write drafts, approve waits, cancel runs, replay runs, change setup, release flows, publish marketplace apps, change billing, or touch secrets need narrow scopes plus explicit confirmation or audit semantics.

Never pass secrets, payment credentials, or raw authorization tokens through MCP tool calls or flow input. Use hosted setup, consent, checkout, or connection URLs for sensitive flows.
Do not pass deploy keys through release_flow; use an operator workflow for
deploy-key-guarded releases.

Safe Client Defaults

Use these defaults when configuring Breyta for an MCP host or gateway:

Start with X-MCP-Readonly: true for exploration and docs review.
Use X-MCP-Toolsets: read,setup,debug,feedback for support and troubleshooting sessions.
Add run only when the user expects the agent to start flow runs.
Add authoring only when the user expects draft creation or validation.
Add release only when the user expects the agent to release/promote an approved flow version.
Prefer explicit X-MCP-Tools allowlists for narrow single-purpose clients.
Log tool calls, arguments, run ids, and resource URIs in the host or gateway audit trail.
Show users the input for call_flow_tool, the flow_literal for create_flow_draft, and the selected flow/version/release note for release_flow before execution when the host supports approvals.

Exposure headers narrow the visible tool set. They do not grant permissions.
The bearer token's principal still needs the matching Breyta capability.
Read-only exposure blocks flow runs, draft writes, and releases but still allows
send_feedback so support sessions can report setup or runtime friction.

Error And Feedback Loop

Use protocol errors to distinguish client/setup problems from flow runtime
problems:

Symptom	Likely class	Next action
`401` or `403` before JSON-RPC result	Auth, token, workspace, or Origin problem	Check endpoint path, bearer token, token workspace, and client Origin behavior.
JSON-RPC `-32602`	Unknown/hidden tool, prompt, resource, or invalid arguments	Re-run `tools/list`, `resources/list`, or `prompts/list` under the same headers.
Tool result with `isError`	Breyta command, validation, setup, billing, or run problem	Read the structured content, linked resources, and run status.
Empty `search_flow_tools` result	No matching callable MCP interface or insufficient visibility	Try `search_flows`, inspect the flow, and verify it defines `:interfaces :mcp`.
Missing or failing connection	Setup or credential problem	Call `list_connections`, then `check_connections` for the selected ids before editing or running the flow.
Step output shape is unclear	Run-debugging problem	Call `inspect_run_step` for the specific run and step id. The response includes the selected step and `stepsSummary.availableStepIds`; it omits unrelated step outputs. Leave `include_step_results` off for timeline/status checks; set it to `true` only when you need that step's bounded captured result preview.

When a tool is hidden or rejected, Breyta returns structured blockers in the
tool error details. Use the reason field to choose the repair:

Blocker reason	Meaning	Repair
`missing_service_account_capabilities`	The authenticated principal or service-account key lacks one or more required Breyta capabilities.	Grant the listed `missingCapabilities` to the principal/key; if using a service account, mint/use a key from that account, then retry.
`read_only_policy`	The MCP server entry has `--read-only` or `X-MCP-Readonly`, but the tool can mutate state.	Remove read-only only after the user approves mutating access for that server entry.
`toolset_policy`	`--toolsets` or `X-MCP-Toolsets` does not include any toolset containing the requested tool.	Add one listed `toolToolsets` value, such as `run` for `call_flow_tool`, `authoring` for draft creation, or `release` for `release_flow`.
`include_tools_policy`	`--tools` or `X-MCP-Tools` allowlists tools and omitted this one.	Add the tool name to the allowlist or remove the allowlist.
`exclude_tools_policy`	`--exclude-tools` or `X-MCP-Exclude-Tools` explicitly hides the tool.	Remove the tool from the exclude list if the user wants it available.

If an agent encounters MCP friction, call send_feedback with:

summary: short issue title
details: what happened and expected behavior
area: mcp, docs, runtime, flow-interface, setup, or other
resource_uri, run_id, or flow_slug where available
redacted, bounded context

Do not include raw headers, access tokens, API keys, OAuth codes, payment
details, prompt-injected secrets, or full private payloads in feedback context.

Run-control tools such as cancellation and wait approval are not exposed through
the workspace MCP server. Use existing Breyta run-control workflows for those
actions.