Connect Breyta MCP To Agentic Coding Tools

Use this page when you want a coding agent to discover, inspect, build, debug,
and run Breyta flows through the workspace MCP server.

A common setup is one MCP server entry per Breyta workspace. That single
workspace endpoint gives access to callable workspace flows and installed
public-flow app instances that define :interfaces :mcp; use a separate
per-flow server entry only when you want deliberate per-flow isolation.

Prerequisites

1. Choose the Breyta 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 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 setup that can discover flows,
   inspect MCP interfaces, inventory connections, read step references, 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 for MCP server entries that expose the
   run toolset or allow call_flow_tool. Keep installations.read when the
   agent should discover or call installed public-flow tools. Add flows.manage
   only when the agent should create or update drafts through
   create_flow_draft or release approved versions through release_flow.

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.

4. Store the bearer token outside version control.

   Most examples below use BREYTA_MCP_TOKEN. If your client does not support
   environment interpolation for headers, use that client's local user config or
   secret prompt mechanism instead of committing the bearer token.

Smoke Test

After adding the server, ask the agent to:

Use the Breyta MCP server. List available resources, read breyta://mcp-docs/overview, call get_workspace_context, then search for callable flow tools.

Then verify:

• If the client exposes MCP resources, resources/list includes
  breyta://mcp-docs/overview and breyta://mcp-docs/client-setup.
• tools/list includes search_flows, search_flow_tools,
  inspect_flow_tool, call_flow_tool, get_run_status, list_connections,
  check_connections, get_flow_definition, and send_feedback, subject to
  token scopes and any narrowing headers.
• get_workspace_context reports the expected workspace id.
• search_flow_tools returns callable flow MCP interfaces when the workspace
  contains flows or installed public-flow apps with :interfaces :mcp.

If the agent hits setup friction, ask it to call send_feedback with area
setup or mcp and redacted context.

Compatibility Notes

Breyta's workspace MCP endpoint is a hosted Streamable HTTP MCP endpoint:

• Use HTTP or Streamable HTTP mode, not legacy SSE mode.
• The endpoint accepts JSON-RPC over POST and may return a normal JSON
  response instead of an SSE stream.
• The endpoint returns 405 Method Not Allowed for GET, which the MCP
  transport allows when the server does not offer a standalone server-sent event
  stream.
• Clients must send Content-Type: application/json and an Accept header that
  allows both application/json and text/event-stream.
• Breyta accepts the common negotiated protocol versions 2025-11-25,
  2025-06-18, and 2025-03-26.
• Configure the Authorization header explicitly. Breyta does not rely on MCP
  OAuth discovery for bearer-token access.
• Native desktop and CLI clients should not send a browser Origin header.
  Browser-origin requests are accepted only when the origin matches the endpoint
  host.

Not every MCP host exposes every MCP primitive in the same UI. Zed currently
surfaces tools and prompts but not general resources, so use
get_workspace_context, search_flows, search_flow_tools, and the public docs
page there instead of relying on resources/read.

Official Registry And Directory Metadata

Breyta Workspace MCP is published as a workspace-scoped remote MCP server named:

ai.breyta/workspace-mcp

The registry manifest is server.json in the Breyta CLI source. It points to
the hosted endpoint template:

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

Use the required workspace_id variable and an Authorization header whose
value is Bearer <Breyta MCP token>. For read-only listings or managed
workspaces, add X-MCP-Readonly: true and a narrow X-MCP-Toolsets value such
as read,setup,debug,feedback.

Directory scanners can read public static metadata at:

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

The server card is for discovery and scanning only. It does not replace the
workspace-specific MCP endpoint, and it does not grant access to any workspace.
Reviewed directories such as Claude and ChatGPT/OpenAI may require an
OAuth-compatible auth path, demo workspace, test credentials, privacy review,
and complete tool safety annotations before public approval.

Direct HTTP Or Stdio Proxy

Use direct HTTP MCP when the client supports hosted Streamable HTTP MCP servers.
Use the Breyta CLI stdio proxy when the client, gateway, or ACP-compatible agent
only supports stdio MCP servers.

The CLI commands in this section are setup helpers: they create copyable MCP
client config, run the stdio proxy when direct HTTP is unavailable, and verify
the connection. After setup, the agent can use Breyta MCP tools, resources, and
prompts directly for MCP tasks.

Both forms are workspace-bound. Do not use a mutable default workspace for MCP
server entries; generate one named entry per workspace.

Print a direct HTTP config:

breyta mcp config \
  --workspace-id ws-acme \
  --provider opencode \
  --transport http \
  --toolsets read,feedback

Print a stdio proxy config:

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.

The stdio proxy command used by generated configs is:

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

Verify setup without invoking mutating tools:

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

breyta init --mcp --mcp-workspace-id ws-acme can print the same workspace-bound
config while bootstrapping a local agent workspace. ACP exposure is just MCP
server configuration passed into the ACP session; Breyta does not define
Breyta-specific ACP custom methods.

VS Code And GitHub Copilot

VS Code stores MCP configuration in mcp.json. Workspace config lives at
.vscode/mcp.json; user config is available from the command palette with
MCP: Open User Configuration.

Use this shape:

{
  "servers": {
    "breytaWsAcme": {
      "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
    }
  ]
}

Open Copilot Chat in Agent mode, enable the Breyta server in the tools picker,
and run the smoke test.

Codex

Codex can add Streamable HTTP MCP servers from the CLI. Store the token in an
environment variable before launching Codex:

export BREYTA_MCP_TOKEN="..."
codex mcp add breytaWsAcme \
  --url https://flows.breyta.ai/api/workspaces/ws-acme/mcp \
  --bearer-token-env-var BREYTA_MCP_TOKEN
codex mcp list

Equivalent ~/.codex/config.toml shape:

[mcp_servers.breytaWsAcme]
url = "https://flows.breyta.ai/api/workspaces/ws-acme/mcp"
bearer_token_env_var = "BREYTA_MCP_TOKEN"

[mcp_servers.breytaWsAcme.http_headers]
"X-MCP-Readonly" = "true"
"X-MCP-Toolsets" = "read,setup,debug,feedback"

Use the TOML form when you want Codex to enforce Breyta narrowing headers; the
codex mcp add --url command only covers the URL and bearer token.

Add a short project instruction when you want Codex to use the server without
being reminded:

Use the Breyta MCP server for Breyta flow discovery, setup checks, flow-tool calls, run debugging, and feedback.

Claude Code And Claude Cowork Sessions

Claude Code supports HTTP MCP servers through claude mcp.

export BREYTA_MCP_TOKEN="..."
claude mcp add --transport http --scope user \
  breyta-ws-acme \
  https://flows.breyta.ai/api/workspaces/ws-acme/mcp \
  --header "Authorization: Bearer $BREYTA_MCP_TOKEN"
claude mcp list

Use --scope project instead of --scope user when the server should be
shared through a project .mcp.json without embedding credentials. In a Claude
Code session, run /mcp and confirm the Breyta server is connected.

For JSON setup:

claude mcp add-json breyta-ws-acme \
  '{"type":"http","url":"https://flows.breyta.ai/api/workspaces/ws-acme/mcp","headers":{"Authorization":"Bearer '"$BREYTA_MCP_TOKEN"'"}}' \
  --scope user

Claude cowork-style environments that read Claude Code MCP config should use the
same HTTP endpoint and authorization header.

Cursor And cursor-agent

Cursor reads MCP config from .cursor/mcp.json for the project or
~/.cursor/mcp.json globally. The Cursor CLI uses the same MCP configuration as
the editor.

{
  "mcpServers": {
    "breyta-ws-acme": {
      "type": "http",
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BREYTA_MCP_TOKEN}"
      }
    }
  }
}

Verify from the CLI when available:

cursor-agent mcp list
cursor-agent mcp list-tools breyta-ws-acme

Windsurf

Windsurf Cascade stores MCP config in ~/.codeium/windsurf/mcp_config.json and
uses serverUrl or url for remote HTTP MCP servers.

{
  "mcpServers": {
    "breyta-ws-acme": {
      "serverUrl": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BREYTA_MCP_TOKEN}"
      }
    }
  }
}

Restart or refresh Cascade MCP servers, then run the smoke test.

Cline

Cline CLI config is ~/.cline/mcp.json. In the IDE extension, open the Cline
MCP Servers view, choose Configure, and edit the JSON under mcpServers. You
can also use the Remote Servers tab with Streamable HTTP.

{
  "mcpServers": {
    "breyta-ws-acme": {
      "type": "streamableHttp",
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer <BREYTA_MCP_TOKEN>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Keep autoApprove empty unless you have narrowed the server with read-only
headers and reviewed the exposed tools.

Roo Code

Roo Code supports global MCP settings and project settings. Use project
configuration at .roo/mcp.json when the server should be tied to one repo; use
the global MCP settings UI for personal setup.

{
  "mcpServers": {
    "breyta-ws-acme": {
      "type": "streamable-http",
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer <BREYTA_MCP_TOKEN>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Prefer manual approval for call_flow_tool, create_flow_draft, and
release_flow.

Continue

Continue uses MCP only in Agent mode. If you are editing an existing
.continue/config.yaml, add the mcpServers block. If you are creating a
standalone file such as .continue/mcpServers/breyta.yaml, include the
metadata fields too:

name: Breyta MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: Breyta workspace ws-acme
    type: streamable-http
    url: https://flows.breyta.ai/api/workspaces/ws-acme/mcp
    requestOptions:
      headers:
        Authorization: "Bearer <BREYTA_MCP_TOKEN>"

Continue can also read JSON MCP files copied from Claude, Cursor, or Cline when
placed in .continue/mcpServers/.

Gemini CLI

Gemini CLI supports MCP server management commands and project or user scope.

export BREYTA_MCP_TOKEN="..."
gemini mcp add --transport http --scope user \
  breyta-ws-acme \
  https://flows.breyta.ai/api/workspaces/ws-acme/mcp \
  --header "Authorization: Bearer $BREYTA_MCP_TOKEN"
gemini mcp list

Equivalent settings.json shape:

{
  "mcpServers": {
    "breyta-ws-acme": {
      "type": "http",
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer <BREYTA_MCP_TOKEN>"
      }
    }
  }
}

Use /mcp list inside Gemini CLI if tools do not appear.

opencode

opencode configures MCP servers under the mcp key in opencode.json or
opencode.jsonc. Use type: "remote" for the hosted Breyta endpoint.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "breyta-ws-acme": {
      "type": "remote",
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:BREYTA_MCP_TOKEN}"
      }
    }
  }
}

Useful commands:

opencode mcp add
opencode mcp list

If the server exposes many tools in a large workspace, use opencode tool
controls or Breyta X-MCP-Toolsets / X-MCP-Readonly headers to keep the
available context focused.

Goose

Goose treats MCP servers as extensions. Use the interactive setup:

goose configure

Then choose:

• Add Extension
• Remote Extension (Streamable HTTP)
• URL: https://flows.breyta.ai/api/workspaces/ws-acme/mcp
• Authorization header: Bearer <BREYTA_MCP_TOKEN>
• Timeout: a value appropriate for flow calls, for example 300

Use Goose access controls if you want the agent to ask before running tools
that mutate files or call external services.

Zed

Zed uses context_servers in its settings rather than mcpServers.

{
  "context_servers": {
    "breyta-ws-acme": {
      "url": "https://flows.breyta.ai/api/workspaces/ws-acme/mcp",
      "headers": {
        "Authorization": "Bearer <BREYTA_MCP_TOKEN>"
      }
    }
  }
}

You can also add the server from the Agent Panel settings view with Add Custom
Server.

Optional Narrowing Headers

Use these when the MCP host supports custom headers:

Headers narrow the visible tool set. They do not grant permissions; the token
must still have the matching Breyta capabilities. Read-only exposure blocks flow
runs, draft writes, and releases but still allows send_feedback for support
sessions when the token has feedback.send.

Troubleshooting

Client References

• Claude Code MCP docs: https://code.claude.com/docs/en/mcp
• OpenAI/Codex Docs MCP setup: https://developers.openai.com/learn/docs-mcp
• Cursor MCP docs: https://docs.cursor.com/context/model-context-protocol
• VS Code MCP configuration: https://code.visualstudio.com/docs/copilot/reference/mcp-configuration
• Windsurf Cascade MCP docs: https://docs.windsurf.com/windsurf/cascade/mcp
• Cline MCP docs: https://docs.cline.bot/mcp/configuring-mcp-servers
• Continue MCP docs: https://docs.continue.dev/customize/deep-dives/mcp
• Gemini CLI MCP docs: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
• opencode MCP docs: https://opencode.ai/docs/mcp-servers
• Goose extension docs: https://goose-docs.ai/docs/getting-started/using-extensions/
• Zed MCP docs: https://zed.dev/docs/ai/mcp