Troubleshooting

Fixes for the common problems when connecting the Superflow MCP server.

The client won’t add the server

There's no option to add a custom connector

Custom connectors are gated by plan. On claude.ai they need Pro or Max, or a Team or Enterprise workspace where an admin has enabled connectors; on ChatGPT they need Plus, Pro, Business, Enterprise, or Edu. On a managed workspace an admin has to allow custom connectors first, and ChatGPT may also require developer mode.

If you can’t get that changed, point your client at the demo endpoint instead. It’s read-only sample data, but it needs no sign-in and no plan upgrade.

The form is asking for a client ID and secret

Leave them blank. Superflow supports dynamic client registration, so your client registers itself when it connects. There are no credentials to copy.

The URL is rejected or the server never responds

Check the URL is exactly https://mcp.usesuperflow.ai/mcp — including the /mcp path. Some clients silently drop a trailing slash or a missing path and then fail with a generic connection error.

Sign-in fails or keeps looping

The browser window opens and immediately closes

Usually a blocked pop-up or a redirect the browser dropped. Allow pop-ups for the client, then start the connection again. If your client opens the sign-in in an embedded browser, try copying the URL into your normal browser.

Signed in, but the client still shows disconnected

The consent screen has to be completed, not just the sign-in. If you closed the window on the permissions step, no grant was created. Remove the server from your client and add it again to restart the flow.

Wrong workspace

The grant is scoped to the workspace you chose during sign-in. To switch, revoke the connection and reconnect, then pick the right workspace on the consent screen.

Tools are missing or failing

The assistant says it can't see any Superflow tools

Restart the client after adding the server — most clients only read MCP config at startup. Then check the client’s MCP panel (/mcp in Claude Code and the Gemini CLI, Settings → MCP in Cursor) to confirm Superflow is listed and connected.

A tool returns a permission error

You didn’t grant that scope. Each capability — running agents, creating projects, reading analytics, inviting people — is a separate scope on the consent screen. Reconnect the server and approve the scopes you need.

Tools also can’t exceed your own access. If your Superflow account can’t do something, neither can the assistant.

An agent run never finishes

Runs are asynchronous, and a full-page review takes a couple of minutes. The assistant polls get_agent_run until it completes, so give it time before asking again.

If it fails outright, the usual causes are the same as for any agent run: the page isn’t publicly reachable, the project has no agents enabled, or the workspace is out of AI credits.

verify_installation says a project isn't installed

The snippet has to be live on the URL the project points at. Check that you published the site after pasting the snippet, that the URL in the project matches the environment you deployed to, and that the page isn’t behind authentication or deployment protection.

See the setup guide for your platform, and the CSP rules if your site sets a strict Content Security Policy.

Disconnecting

Removing the server from your client’s config stops it calling Superflow, but doesn’t revoke the access token it already holds. To revoke the grant itself, disconnect Superflow from the client’s connected apps screen, or from the MCP settings in your Superflow dashboard. Access dies immediately; anything the assistant already created stays in your workspace.

Still stuck? Reach us from the support section in the dashboard and include the client you’re connecting from.