Skip to main content

Troubleshooting

Agent won't connect​

  • Make sure outbound :3001 (WebSocket) is open on your network.
  • Check you're authenticated: mcp-gw whoami should print your stored credentials. mcp-gw list should reach the gateway and return your tunnels.
  • If you passed --id, confirm it's a real tunnel id (mcp-gw list).

502 Bad Gateway on the public URL​

The agent isn't connected, or it dropped the connection. Check the terminal where mcp-gw create is running — it should say WS connected. If it exited, run it again.

504 Gateway Timeout on the public URL​

The agent is connected, but your local MCP server didn't respond in time.

  • Is the local server actually running on the port you passed to --target?
  • Try curl http://localhost:8080/ from your machine — does it respond?
  • For stdio servers wrapped with supergateway, check that supergateway itself didn't crash (the subprocess may have exited).

Tools don't appear in Claude / Cursor​

  • Make sure the URL ends with /mcp (the streamable-HTTP path).
  • Hit https://<tunnel>.mcp-gateway.info/mcp with curl — you should get a JSON response, not 404.
  • Restart the client after editing its config.

The menu shows a tunnel as active​

active means another agent is already connected to that tunnel (maybe an mcp-gw create still running in another terminal). Reconnecting will take over the tunnel; stop the other agent first, or pick Create a new tunnel.

Update the CLI​

npm install -g @alexdive/mcp-gw@latest

Compare your installed version to the latest published one:

npm ls -g @alexdive/mcp-gw          # installed
npm view @alexdive/mcp-gw version   # latest on npm

Cannot find module when starting the CLI​

Reinstall:

npm uninstall -g @alexdive/mcp-gw
npm install -g @alexdive/mcp-gw

Docker volume permissions on Linux​

If docker run -v mcp-memory:/app/dist fails with permission errors, run docker as your user (add yourself to the docker group) and re-login.