Builder MCP Troubleshooting v2

Use this checklist when a Builder MCP client cannot connect, discover context, call Tools, Debug, or save a Workflow.

Endpoint and OAuth

Use https://<environment-hostname>/mcp/builder, including the Environment's complete hostname and the /mcp/builder path.
Open the endpoint in a browser and confirm that Flowgear Builder guidance appears.
Confirm DNS and certificate trust for that hostname.
Reauthenticate the flowgear MCP server when OAuth is missing or expired.
Check that the signed-in user has the required Site Administrator development access.

Missing guidance or Tools

The agent should read flowgear://builder/guidance once, this is also a suitable way to verify that the MCP server is accessible to the agent. Some agents don't support MCP resources, in that case ask that they call GetBuilderGuidance once instead.

If Tools appear incomplete, reconnect the server and start a new client session so the Tool list and schemas are rediscovered.

Wrong Site or Environment

Ask the agent to call GetBuilderContext. The hostname determines Tenant, Site, and Environment. Register a separate MCP server (with a unique name) for each tenant you want to manage via Builder MCP.

If you are working in a project, folder or repository, ensure your AGENTS.md file indicates the correct MCP server name to use. By default, Flowgear sample repositories use the name flowgear for MCP servers which will be incorrect if you have more than one registered.

Discovery failures

Search before assuming a Node, Method, Workflow, folder, Cluster, or Connection exists. An unavailable option can be caused by runtime version, permissions, installed Node version, Cluster compatibility, or current Environment scope.

Save conflicts

An existing Workflow update requires its Key and current FileHash. A stale hash means another revision was saved. Fetch the Workflow again, reconcile the intended edit, Debug it, and retry with the new hash. Do not invent or reuse an older hash.

Client approvals and timeouts

A client can block a Tool while waiting for approval or stop waiting before a long Debug call completes. Review per-server Tool approval and timeout settings, then retry only after confirming whether the previous call took effect.