Builder MCP Server v2

Builder MCP gives an external coding agent the Flowgear Tools and guidance required to discover, create, Debug, inspect, and save Workflows.

Use it when the agent also needs to work in a local repository, such as a Flowgear App frontend. For an agent operating only on the current Console design, use the AI Workflow Assistant.

Instructions for registering Builder MCP are available in the Console from MCP in the main navigation.

Upcoming changes

An upcoming Flowgear release changes how Builder MCP connects, what each connection can access and what the agent can do. Existing clients will need to be registered again. The rest of this article describes Builder MCP as it works today.

One URL for every Site

Builder MCP moves from the Environment hostname to your Tenant hostname:

https://<example>.flowgear.net/mcp/builder

One connection covers every Site and Environment you allow when you connect, so you no longer need a separate server for each Site. The agent picks the Site and Environment for each action. When you don't name an Environment, it works in the first Environment in that Site that the connection allows.

The Environment-hostname URL stops serving Builder MCP Tools and returns a message pointing to the Tenant URL instead. Remove each existing Builder MCP server from your client, add it again with the Tenant URL, and sign in again.

Choose access when you connect

When you sign in, you choose which Sites and Environments the agent may use. For each Environment, choose no access, read, or read and write. You also choose how long this consent lasts: 1 hour, 8 hours, 1 day, 7 days, 30 days, or with no expiry. When the consent ends, the client has to reconnect and you choose again.

• By default, every Site is selected with its first Environment set to read and write, and the consent has no expiry.
• The first time you allow access beyond a Site's first Environment, which may include Production, the expiry changes to 1 hour. You can choose a different one.
• A consent with no expiry that reaches beyond a Site's first Environment needs an extra confirmation.
• A consent with no expiry does not end. As today, a client that is not used for 7 days has to sign in again.
• One connection can reach at most 50 Environments.
• Workflow logs are not separated by Environment. Read access to any Environment in a Site includes that Site's logs from every Environment.

To change the access later, reconnect the server in your client.

Reconnect for more access

When the agent calls a tool where the connection does not allow it, but your own permissions do, Builder MCP asks the client to reconnect. The access the agent needs is already selected when you sign in again, and you can change it before you accept. When your own permissions do not allow the action, it is denied, and reconnecting does not help.

Permissions

Builder MCP will no longer require the fixed permission bundle or Site Administrator access described below. The agent can do what you can do in the Console: each tool checks your own permissions for that action, in the Site and Environment the call uses. Because each tool is checked separately, a user whose role allows some actions but not others can use only the matching tools.

The access you choose when connecting can only narrow your permissions; it never adds to them. Removing your permissions also removes the connection's access.

On a Site without release management, saving a Workflow publishes it to every Environment. The connection only needs read and write access in the first Environment for this, but you need permission to change Workflows in each Environment.

v1 Runtime Workflows

The agent can find and read v1 Runtime Workflows, their Nodes, logs and folders as well as v2 Runtime Workflows. When it reads a v1 Runtime Workflow, values longer than 1,000 characters are returned only when the agent asks for that value. Secrets and binary values are not returned.

Changing, debugging, enabling and promoting Workflows remain available for v2 Runtime Workflows only.

New actions

You can ask the agent to:

• Promote a Workflow to the next Environment on a Site with release management. The agent always saves a Workflow in the Site's first Environment, and promotion moves it on from there.
• Enable a Workflow in an Environment where it is published, and check whether a Workflow is enabled. Enabling a Workflow does not change its API Key access.
• Create and update Connections with their non-secret values. You enter passwords, keys and certificates on the Connection page.
• Create Connection folders, and move Workflows, Connections and folders between folders.

Secrets

Builder Guidance tells the agent never to ask for passwords, API keys, tokens or certificates in the chat. Instead, it links the Console page where you enter them: the Connection page for Connection credentials, the API Keys screen, or the Key/Value Management screen.

Model warning

If your agent uses a model that Flowgear has not tested for building Workflows, the agent tells you so at the start of the session.

Endpoint and context

Register the Test Environment endpoint:

https://<environment-hostname>/mcp/builder

The hostname fixes the Tenant, Site, and Environment. Builder MCP is a stateless MCP server and uses Flowgear OAuth. Verify the URL in a browser before registration; the expected Flowgear 405 Method Not Allowed message confirms the MCP route is reachable.

Builder MCP can create records and Debug Workflows against connected systems. Use a development Environment and review client Tool approvals. The server requires the fixed Builder development permission bundle; the customer-facing prerequisite is Site Administrator access.

Set up a client

Open MCP from the Console's main navigation and use the Builder MCP section. The quickest path is to copy the Setup with your Coding Agent prompt and paste it into your coding agent. The prompt already contains the Server URL and the recommended server name, so you do not need to copy either value separately.

To set up a client manually, copy the Server URL and Recommended name from the same section. Prefer manual setup? shows Codex, Claude Code, and GitHub Copilot CLI commands that already use the recommended name. The commands in this article use <recommended-name> as a placeholder for that value.

The recommended name keeps each Flowgear MCP server distinguishable in your client. It is a recommendation, and you can choose a different name where your client allows it. Use the same name in every add, login, and authentication step for that server.

You can keep several Flowgear Builder MCP servers configured at the same time, for example one for each Tenant and Site you work with. Select the server for the Tenant and Site you are working on, then confirm it with GetBuilderContext.

• Connect Codex to Builder MCP
• Connect Claude Code to Builder MCP

Other clients must support remote HTTP MCP, OAuth, Tools, and ideally Resources. When Resources are unavailable, use the guidance fallback described below.

OpenAI Codex

Install and sign in to Codex, then register the server:

codex mcp add <recommended-name> --url https://<environment-hostname>/mcp/builder

The add command normally starts OAuth; if it does not, run codex mcp login <recommended-name>. Codex reads flowgear://builder/guidance, so it does not normally need GetBuilderGuidance. See Codex CLI and Codex MCP.

Anthropic Claude Code

Install and sign in to Claude Code, then register the server:

claude mcp add --transport http <recommended-name> https://<environment-hostname>/mcp/builder

Run /mcp, choose Authenticate for <recommended-name>, and complete Flowgear sign-in. Claude Code reads flowgear://builder/guidance. See the Claude Code Quickstart and Claude Code MCP documentation.

GitHub Copilot

GitHub Copilot and Microsoft Copilot are separate products.

GitHub Copilot CLI

After installing and signing in to Copilot CLI, register Builder MCP:

copilot mcp add --transport http <recommended-name> https://<environment-hostname>/mcp/builder

Start each Builder session with:

copilot --allow-all-mcp-server-instructions

The flag applies only to the current session. Flowgear testing found that Copilot CLI exposed Tools but not Resources, so call GetBuilderGuidance once at the start. See installing Copilot CLI, adding MCP servers, and the CLI command reference.

GitHub Copilot for Visual Studio Code

Add this server to the Visual Studio Code MCP configuration, replacing <recommended-name> with the recommended name from Console:

{
  "servers": {
    "<recommended-name>": {
      "type": "http",
      "url": "https://<environment-hostname>/mcp/builder"
    }
  }
}

Visual Studio Code supports Resources, but Flowgear testing found that Builder Guidance did not always load automatically. Call GetBuilderGuidance when it is absent. See MCP servers in Visual Studio Code and GitHub's Visual Studio Code setup.

GitHub Copilot App

Add the Flowgear server under MCP Servers in the App settings, using the recommended name from Console. Connection, OAuth, Tool discovery, and Tool calls worked during Flowgear testing, but server instructions and Builder Guidance were inconsistent and the App did not offer the CLI instructions flag. Call GetBuilderGuidance at session start; Copilot CLI and Visual Studio Code gave more consistent results. See Customize the GitHub Copilot App.

Microsoft Copilot

Microsoft Copilot Studio

Copilot Studio gave the most consistent Microsoft Copilot result during Flowgear testing. It is a managed agent and cannot see a local repository.

Follow Connect a Copilot Studio agent to an MCP server. Add the Builder MCP URL with OAuth 2.0 authentication and Dynamic discovery, create the connection, and complete Flowgear authentication.

Copilot Studio does not apply Builder Guidance automatically. Call GetBuilderGuidance in a test conversation, copy the complete result into the agent's Instructions, save, and begin a new conversation. This is a snapshot, so refresh it after major guidance changes. See adding MCP Tools and Resources and writing agent instructions.

Microsoft 365 Copilot App

Users consume a published Copilot Studio agent from the Microsoft 365 Copilot App, but configure the Builder MCP URL in Copilot Studio. See the Microsoft 365 Copilot App overview.

Other clients

Other MCP clients, including clients such as Gemini CLI, can use Builder MCP when they support remote HTTP MCP servers, OAuth 2.0, and MCP Tools.

Load guidance and verify context

Before the first build call:

1. Load flowgear://builder/guidance once.
2. If the client cannot read Resources and guidance is absent, call GetBuilderGuidance once instead.
3. Call GetBuilderContext and confirm the returned Tenant, Site, and Environment.

Do not load both guidance copies. See Builder Guidance.

Authoring loop

The verified loop is:

1. Discover exact Node, Method, version, template, Connection, schema, Folder, and Cluster contracts.
2. Build the smallest runnable slice.
3. Save a blank shell for a new Workflow to obtain its Key and FileHash.
4. Debug the current YAML under that key.
5. Repair the latest gating failure and repeat.
6. Save only the tested YAML with the latest file hash.

Use Build a Workflow with Builder MCP for creation and Edit an Existing Workflow with Builder MCP for concurrency-safe updates.