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.

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.

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.