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. If the client runs on another machine, see Client on another machine.
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 on another machine

Symptoms

• Your AI client runs over SSH, on a VPS, or in a dev container, and you approve Gummble in a browser on your own computer.
• After you click Connect, the browser shows "This site can't be reached" for an address on 127.0.0.1, localhost or [::1].
• The client keeps waiting for authorization.

Why

Clients such as Claude Code, Codex and mcp-remote receive the OAuth result on localhost of the machine they run on. Your browser sends it to localhost on your own computer instead, so the client never gets it.

Fix: Claude Code and Codex

Both CLIs have a sign-in mode for remote machines. They print the link and then ask you to paste the address your browser ends up on:

claude mcp login gummble --no-browser
codex mcp login gummble --no-browser

Open the printed link in a browser on any computer and approve the connection. When the browser shows the connection error, copy the full address from the address bar and paste it into the terminal within 60 seconds.

Fix: other clients

Hand the callback to the client yourself:

1. Start authorization from the client as usual and open the printed link in any browser.

2. Approve the connection. When the browser shows the connection error, copy the full address from the address bar.

3. Within 60 seconds, run this on the machine that runs the client:

   curl 'http://127.0.0.1:PORT/callback?code=...&state=...'

   Paste the address you copied. Keep the single quotes so the shell does not split it at &.

Either way, the client finishes sign-in and stores its own refresh token, so you do this once per machine. The code is bound to the client that started the request (PKCE), so it is useless to anyone else, and it expires after 60 seconds. If it expires, start the authorization again.

If you already forward ports over SSH, ssh -L PORT:127.0.0.1:PORT to the client machine also works. Use the port from the callback address, which can change on every attempt.

Do not copy tokens between machines, and do not paste a browser session token into a client config. Each machine authorizes on its own.

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.