Troubleshooting

Start here when an MCP client can see the Gummble server but install, authorization, or tool calls do not complete.

Plan required

Symptoms

• The client connects but the first tool call returns an entitlement or upgrade error.
• You are redirected to an upgrade CTA during MCP setup.
• The server responds, but no usable design data is returned.

Fix

Upgrade to a plan that includes MCP access, then restart the client auth flow. If the client cached a failed token, disconnect or remove the gummble server first, then authorize again.

OAuth opens but fails

Symptoms

• A browser window opens, but the callback never reaches the MCP client.
• The consent page loops back to sign-in.
• The client reports that authorization was cancelled or timed out.

Fix

1. Sign in to Gummble with the same browser profile that opened the OAuth page.
2. Allow popups, cookies, and localhost callbacks for the auth flow.
3. Disable extensions that block redirects for api.gummble.com or gummble.com.
4. Retry from the client instead of refreshing the callback URL manually.

If the client supports clearing MCP credentials, clear the Gummble entry and run the auth flow again.

Client supports SSE only

Symptoms

• The client asks for an SSE endpoint.
• https://mcp.gummble.com/mcp is rejected as an unsupported transport.
• The client was built before Streamable HTTP support shipped.

Fix

Use the Streamable HTTP endpoint whenever possible:

https://mcp.gummble.com/mcp

For legacy SSE-only clients, use:

https://mcp.gummble.com/sse

If the client supports both, prefer Streamable HTTP. It is the primary Gummble MCP transport.

Token/scope missing

Symptoms

• tools/list returns empty.
• Tool calls fail after OAuth succeeds.
• The client says the token is missing a scope or audience.

Fix

Disconnect the gummble MCP server from your client and authorize again. The consent screen should request MCP scopes such as mcp:tools and issue a token for:

https://mcp.gummble.com/mcp

If you are building a custom client, make sure the authorize and token requests include the MCP resource parameter and that token refreshes use the same resource audience.

Expired or revoked token

Symptoms

• Tool calls repeatedly return invalid_token after the connection worked.
• The client keeps retrying instead of opening a fresh OAuth flow.
• Gummble Settings shows Authorization expired or Reconnect required.

Fix

1. Restart the client once so it can use its stored refresh token. Do not keep retrying the expired access token.

2. If the error repeats, open Gummble MCP Settings, choose Reconnect for that client, and complete browser authorization.

3. If the client still replays the old credential, clear only its Gummble MCP credential and reconnect:

   • Claude Code: run claude mcp remove gummble --scope user, add Gummble again, then run /mcp and choose Authenticate.
   • Codex: run codex mcp logout gummble, followed by codex mcp login gummble.
   • Other clients: remove the Gummble MCP connection, add https://mcp.gummble.com/mcp again, and approve the new OAuth request.

If your trial or subscription ended, restore an eligible plan before reconnecting. Reauthorization does not bypass entitlement checks.

Still stuck

Send support the client name, the server URL used, the approximate timestamp, and the exact error message. If this is a custom integration, include the OAuth step that failed and the HTTP status code.