Breyta Workspace MCP

The workspace MCP server is an agent-facing control plane for one Breyta workspace. It exposes a small set of intent-shaped tools instead of mirroring every Breyta HTTP or CLI command.

New User Setup

Set up one MCP server entry per workspace. That single workspace server can
search, inspect, and call accessible workspace flows and installed public-flow
installations that define :interfaces :mcp; users do not need one MCP server
entry per flow unless they deliberately want per-flow isolation.

1. Choose the workspace id.

   The production endpoint shape is:

   https://flows.breyta.ai/api/workspaces/{workspace_id}/mcp
   

2. Choose an authenticated Breyta bearer token for the coding agent.

   The token can belong to any Breyta principal with the needed capabilities.
   A service account is not required when the MCP host already has a suitable
   user or workspace bearer token.
   A scoped service-account key is recommended for unattended or shared agent
   setups because it can be narrowed and rotated independently from a human
   session.

   For an optional read-only service-account client that should discover flows,
   inspect MCP interfaces, inventory connections, read step references, read run
   status, and report feedback:

   breyta service-accounts create \
     --name workspace-mcp-agent \
     --scope flows.read \
     --scope runs.read \
     --scope resources.read \
     --scope installations.read \
     --scope connections.read \
     --scope steps.read \
     --scope feedback.send
   

   For any bearer token, the authenticated principal needs equivalent
   capabilities. Add flows.run only when the MCP client should expose the
   run toolset or call flow MCP interfaces through call_flow_tool. Keep
   installations.read when the client should discover or call installed
   public-flow tools. Add flows.manage only when the MCP client should
   create/update drafts through create_flow_draft or release approved
   versions through release_flow. Avoid workspace.full for normal MCP
   clients.

3. If using a service account, mint an API key.

   breyta service-accounts keys create <service-account-id> --name coding-agent
   

   The returned apiKey is shown once. Store whichever bearer token you use in
   the MCP host's secret input, local user config, or environment, depending on
   the client.

4. Add an HTTP or Streamable HTTP MCP server to the coding agent config.

   Example for workspace ws-acme:

   {
     "servers": {
       "breyta-ws-acme": {
         "type": "http",
         "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
         "headers": {
           "Authorization": "Bearer ${input:breyta_mcp_token}"
         }
       }
     },
     "inputs": [
       {
         "type": "promptString",
         "id": "breyta_mcp_token",
         "description": "Breyta MCP bearer token",
         "password": true
       }
     ]
   }
   

   If the host uses a different config wrapper, keep the same server type, URL,
   and authorization header.

   For client-specific setup snippets for Codex, Claude Code, Cursor,
   Windsurf, VS Code Copilot, Cline, Roo Code, Continue, Gemini CLI,
   opencode, Goose, and Zed, use Connect Breyta MCP To Agentic Coding
   Tools.

   If the client or ACP-compatible host only supports stdio MCP servers, use
   the Breyta CLI proxy instead:

   export BREYTA_MCP_TOKEN="<breyta-bearer-token>"
   
   breyta mcp config \
     --workspace-id ws-acme \
     --provider codex \
     --transport stdio \
     --read-only \
     --toolsets read,setup,debug,feedback
   

   breyta mcp init is an alias for the same config-rendering setup path.

   Generated stdio configs call:

   breyta mcp stdio \
     --workspace-id ws-acme \
     --token-env-var BREYTA_MCP_TOKEN \
     --read-only \
     --toolsets read,setup,feedback
   

Do not put access tokens in query strings or flow inputs. Use an authorization
header or the host application's secret input mechanism.

The workspace endpoint is Streamable HTTP over POST. MCP hosts and gateways
must send JSON-RPC requests with Content-Type: application/json and an
Accept header that allows both application/json and text/event-stream.
GET currently returns a method-not-allowed response because this endpoint does
not offer a standalone server-sent event stream.

Breyta accepts the common negotiated MCP protocol versions 2025-11-25,
2025-06-18, and 2025-03-26. The server responds with the client's requested
version when it is supported, otherwise with the latest supported version. Use
HTTP or Streamable HTTP mode in clients; do not configure the workspace endpoint
as legacy SSE.

Registry And Directory Metadata

Breyta publishes Workspace MCP as one workspace-scoped remote server, not as one
directory entry per flow. The registry name is:

ai.breyta/workspace-mcp

The official MCP Registry manifest lives in the Breyta CLI source as
server.json. It describes the hosted Streamable HTTP endpoint with a required
workspace_id URL variable and an Authorization header supplied by the user or
client secret store.

Directory scanners that cannot authenticate against a workspace endpoint can
read static metadata from:

https://flows.breyta.ai/.well-known/mcp/server-card.json

That server card lists the same public tool names, descriptions, schemas,
resources, prompts, and safety annotations as the authenticated workspace MCP
surface. If a directory requires OAuth for authenticated remote MCP servers,
treat that as a separate reviewed-listing path; the bearer-token setup described
here remains the default direct user and service-account setup path.

Use the same URL and header shape in VS Code, Cursor, Claude, Codex-compatible gateways, or any other host that supports HTTP MCP servers. If a host uses a different config wrapper, keep these fields equivalent:

Configure one named server per workspace when a user needs access to multiple
workspaces.

For stdio proxy verification, run breyta mcp doctor --workspace-id <id> --token-env-var BREYTA_MCP_TOKEN with the same --read-only, --toolsets,
--tools, or --exclude-tools narrowing flags used in the generated config.
The doctor calls initialize and tools/list; it does not invoke mutating
tools.

If a tool call is rejected after setup, inspect
structuredContent.details.blockers in the tool result. missingCapabilities
means the authenticated principal lacks Breyta capabilities such as
flows.run, connections.read, or flows.manage; toolset_policy,
read_only_policy,
include_tools_policy, and exclude_tools_policy mean the MCP server entry is
narrowing the visible tool surface. Adjust scopes and MCP narrowing separately.

First Connection Checklist

When setting up a new client, verify the protocol surface before asking an
agent to do real work:

1. Connect and call initialize.
2. Call resources/list and read breyta://mcp-docs/overview.
3. Call resources/templates/list and confirm the expected flow and run URI templates are visible.
4. Call prompts/list and inspect any workflow prompt the user wants to run.
5. Call tools/list with the intended narrowing headers.
6. Call get_workspace_context and confirm the reported workspace, toolsets, and capability groups.
7. Call list_connections and check_connections when the user expects the agent to build or debug flows that touch external systems.
8. Use search_flow_tools or search_flows before calling any flow tool.
9. Use get_flow_definition, get_step_reference, check_flow_readiness, and inspect_run_step for focused build/debug context instead of loading broad CLI docs or full run logs.
10. Call send_feedback if setup, docs, discovery, or invocation behavior is confusing.

The MCP Inspector is useful for this smoke test because it shows resources,
prompts, tool schemas, and tool execution results in one place. For HTTP MCP,
configure the Inspector with the workspace endpoint and the same bearer token
header the real client will use.

MCP Documentation Surface

Breyta exposes MCP-specific docs as MCP resources so agents do not have to
infer MCP behavior from CLI-oriented pages:

These resources are listed with MCP resource annotations so clients can
prioritize them during context selection. breyta://mcp-docs/{doc_id} is also
available as a template for direct reads.

Use MCP docs for MCP behavior and the normal Breyta docs for deeper flow
language reference:

MCP And CLI Boundaries

Use MCP when the agent needs to discover flows, inspect callable MCP
interfaces, check setup, call a flow tool, debug a run, validate a candidate
definition, create a draft, pull source definitions, release an approved
version, or send feedback.

Use the CLI, UI, or existing operator workflows for credential creation,
connection or secret mutation, marketplace or billing changes, destructive run
control, broad admin work, and local file/project setup. These operations are
intentionally outside the default workspace MCP tool list.

Capability Map

Scope Bundles

Prefer narrow Breyta capabilities:

Avoid workspace.full for normal MCP clients.

Common Server Presets

These presets combine bearer-token capabilities with MCP narrowing headers.
Headers only narrow the visible MCP surface; they do not grant permission
without matching Breyta capabilities.

Tool Exposure Controls

The default server advertises the workspace MCP surface that the current
principal is allowed to use. For bearer tokens, tools outside the authenticated
principal's granted capabilities are hidden from tools/list and rejected at
tools/call; resource templates, prompt workflows, and resource reads are
scoped the same way. Exposure headers can narrow the tool set but cannot widen
it. Clients or gateways can narrow the exposed tools with headers:

tools/list also accepts matching request params for discovery experiments, but call-time enforcement should use headers so the same policy applies to tools/call.

Aggregate Flow Brokering

The workspace endpoint can broker all accessible flow :interfaces :mcp tools:

1. Call search_flow_tools when the goal is to find callable flow tools.
2. Call search_flows for broader flow/template/install discovery when the user is still choosing a flow.
3. Call inspect_flow_tool for the selected flow and tool.
4. Call list_connections, check_connections, or check_flow_readiness when setup or external systems matter.
5. Call call_flow_tool with flow_slug, tool_name, and an input object containing the selected flow tool's input fields. Include installation_id when targeting a specific installed public app instance.
6. Poll get_run_status, inspect specific steps with inspect_run_step, or read breyta://runs/{run_id} and breyta://runs/{run_id}/events.

The workspace server exposes a stable, compact tool list. Flow-specific MCP
interfaces are discovered through search_flow_tools and invoked through
call_flow_tool, so large workspaces do not need one listed MCP tool per flow.

search_flow_tools returns concise entries for callable flow interfaces and
supports text search, browsing, and exact tool-name lookup. Discovery results
are advisory: before a run starts, call_flow_tool loads the selected flow and
verifies that the requested MCP interface is still available.

Public apps that require setup, billing, or installer-owned connections should
be installed, configured, and enabled before an agent invokes them. Do not treat
the workspace MCP broker as a way to run arbitrary public Discover flows before
installation.

Users do not need to install one MCP server per flow unless they want a direct per-flow endpoint.

Tool Catalog

The workspace surface is intentionally small and intent-shaped:

MCP tool argument names use snake_case, matching Breyta's MCP tool names.
Examples: flow_slug, tool_name, run_id, workflow_id,
flow_literal, connection_ids, and include_events.

MCP tools are grouped around agent workflows rather than individual CLI
commands. For example, use check_flow_readiness for setup/readiness context,
and use search_flow_tools, inspect_flow_tool, and call_flow_tool for flow
MCP interfaces. Use the CLI docs for terminal/operator tasks that are not
available through this MCP server.

Tool execution errors, hidden-tool rejections, and tool argument validation
failures are returned as tool results with isError. Protocol errors such as
malformed JSON-RPC envelopes, unsupported methods, and unknown MCP tool names
use JSON-RPC errors. Treat call_flow_tool as long-running work: it starts the
backing run and returns run identifiers and resource links for follow-up reads.
For complete report-style outputs, prefer reading the returned resultResource
with resources/read instead of relying on inline tool text. Textual result
payloads are served from breyta://runs/{run_id}/result with the most specific
safe MIME type Breyta can determine, such as text/html for HTML reports, so
clients such as Claude Desktop can load the full document without clipping it
into the tool response. Result resources also apply credential-focused redaction
before returning textual or JSON content. Breyta viewer envelopes such as
{:breyta.viewer/kind :html :breyta.viewer/value "..."} are unwrapped to their
native textual MIME type when read through the result resource. Typed textual
result reads also include an embedded MCP resource content block for clients that
render artifacts from content blocks instead of only resources/read
contents.

Resources And Prompts

Direct resources:

Resource templates:

Prompts are user-invoked workflows, not hidden automatic behavior:

Feedback

If an agent hits unclear docs, setup friction, runtime errors, or a confusing flow MCP interface, call send_feedback with a short summary and redacted context. Prefer linking resource_uri, run_id, or flow_slug instead of embedding raw private payloads.

Auth Model

This endpoint uses existing Breyta API authentication, including service-account
tokens. Do not describe it as MCP OAuth-complete or rely on OAuth discovery for
access.