MCP Authentication and Hostname Troubleshooting v2

Use this checklist when a Workflow or Builder MCP client cannot reach Flowgear, discover OAuth, authenticate, list tools, or call an eligible Workflow.

Verify the exact endpoint

Use the complete Environment hostname:

Workflow MCP: https://<hostname>.flowgear.net/mcp
Builder MCP:  https://<hostname>.flowgear.net/mcp/builder

Open it in a browser. A Flowgear message with 405 Method Not Allowed is the expected endpoint verification because the route expects an MCP transport request.

A DNS, connection, or certificate error means the hostname is not reachable. A 404 or non-Flowgear response commonly means the wrong hostname or path. Saving a hostname in Site settings does not provision DNS; confirm routing with Flowgear Support.

Diagnose OAuth discovery

If the client reports no authorization support, first verify that it can reach the endpoint. Remove stale credentials or reauthenticate the configured server, then complete sign-in with a user who can access the Site and Environment.

Workflow MCP tool is missing

Confirm that the Workflow:

Has a valid, unique MCP tool contract.
Is published and enabled in the hostname's Environment.
Is assigned to a Delegate MCP user API Key for that Environment.
Permits the signed-in user, who also has effective Environment access.

Refresh the MCP page and allow a short publish/status convergence period.

Builder Tools are unavailable

Builder MCP targets the Test Environment and requires its fixed development permission bundle. Confirm GetBuilderContext, Site Administrator access, Resource/Tool support, and that Builder Guidance was loaded once.

Browser and origin issues

Browser-based MCP clients must originate from an allowed Environment origin and use the supported transport headers. CORS does not replace OAuth or Workflow authorization.