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 <recommended-name> server, or the name you chose when you registered it, when OAuth is missing or expired. For example, run codex mcp login <recommended-name> in Codex, or run /mcp in Claude Code and select Authenticate for <recommended-name>.
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. You can keep several Flowgear MCP servers configured at once. Register a separate Builder MCP server for each Tenant and Site you want to manage, using the Recommended name from the Builder MCP section of the Console's MCP page so each server is distinguishable. If the agent is connected to the wrong Tenant or Site, ask it to use the server registered for the intended target and call GetBuilderContext again.

If your project's agent guidance, such as an AGENTS.md file, names a specific MCP server, make sure it names the server registered for that project's Tenant and Site.

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.