Documentation
MCP + Webhook Troubleshooting
Diagnose failures fast with a practical matrix: symptom, likely cause, exact checks, and safe fixes.
Fastest debug path
- Run
instatunnel doctor --mcpfor MCP readiness checks. - Use provider helper commands from
/dashboardor/docs/webhooks. - Verify endpoint path + signature secret before retrying provider test events.
Tunnel Connection and Access
| Symptom | Likely cause | Quick checks | Fix |
|---|---|---|---|
| 426 Upgrade Required when starting an anonymous tunnel | The CLI is older than 1.1.24 and cannot use the required private connection token. | instatunnel --version npm view instatunnel version | Run npm install -g instatunnel@latest, then restart the tunnel. The CLI manages the token automatically. |
| 400 anonymous tunnel limit reached for your network | Anonymous tunnels are limited to 2 active tunnels and 6 new tunnels per 24 hours per network, or the network has been blocked after abuse. | Stop unused anonymous tunnels Check whether others on your network are using anonymous tunnels | Wait for an active tunnel to expire or stop it, or sign in with a free InstaTunnel account, which is not subject to the anonymous limits. If you believe your network was blocked in error, contact support@instatunnel.my. |
| Browser shows "This is an anonymous InstaTunnel link" before my app | Anonymous tunnels show a one-time warning page to browser visitors so they are not mistaken for a trusted site. | Open the tunnel URL in a browser Check whether the tunnel was started without signing in | Click Continue (remembered for 24 hours). For automated browser tests, send the X-InstaTunnel-Skip-Warning header. Sign in to InstaTunnel to use tunnels without the warning page. API calls and webhooks are not affected. |
| 403 Tunnel suspended | An anonymous or Free-plan tunnel received repeated requests that match phishing-kit behavior and was suspended automatically. Paid plans are not suspended automatically. | Review which routes your local app exposes, especially form handlers such as *_handler.php | Sign in with an InstaTunnel account and start a new tunnel. If the suspension was a mistake, contact support@instatunnel.my with the tunnel URL. |
| 401 when connecting a tunnel | The saved API key does not own that tunnel, or an anonymous connection lacks its issued token. | instatunnel --version Check the account/API key used to create the tunnel | Update the CLI and reconnect with the owning account. For anonymous use, start a new random tunnel with the updated CLI; do not share connection tokens. |
| 409 tunnel already has an active client | Another CLI process is still connected to the same tunnel. | Check other terminals or machines using this subdomain | Stop the existing CLI session before reconnecting. A new connection does not replace the active one. |
| 401 when visiting a protected tunnel | The visitor has not provided the configured password or Basic Auth credentials. | Open the URL in a browser For APIs, inspect the request headers | For --password, use the browser form or send X-InstaTunnel-Password. For --auth, use HTTP Basic Auth. Both features require Pro or Business. |
| A webhook provider cannot reach a protected tunnel | The provider cannot complete a browser password form or send the required auth header. | Check whether the provider supports custom headers or Basic Auth | Use a compatible header if supported. Otherwise, leave that tunnel endpoint unprotected and verify the provider webhook signature in your app. |
MCP Troubleshooting Matrix
| Symptom | Likely cause | Quick checks | Fix |
|---|---|---|---|
| MCP mode is available on Pro and Business plans | Current account plan is Free or the wrong API key is loaded locally. | instatunnel --stats instatunnel doctor --mcp | Upgrade to Pro/Business or set the correct API key with instatunnel auth set-key "it_...". |
| TLS handshake timeout during auth/login | Transient network path issue or corporate gateway latency. | instatunnel doctor --json curl -I https://api.instatunnel.my/health | Retry login (CLI auto-retries), then verify DNS/firewall path. Keep CLI on latest version. |
| Tunnel URL loads: Failed to reach local server localhost:<port> | Local app is not running or wrong port is tunneled. | curl http://localhost:8787 instatunnel doctor --port 8787 | Start local app first, then run instatunnel 8787 --mcp [--transport v2]. |
| MCP client gets 401/403 | Missing/invalid bearer token or endpoint path mismatch. | Confirm client URL ends with /mcp Verify Authorization header value | Set correct URL and token. For HTTP MCP: {"headers":{"Authorization":"Bearer YOUR_MCP_TOKEN"}}. |
| Streaming behavior not working | Using transport v1 for a streaming MCP workflow. | instatunnel --version Current command flags | Use CLI 1.1.7+ and start with --transport v2 for streaming clients. |
Webhook Troubleshooting Matrix
| Symptom | Likely cause | Quick checks | Fix |
|---|---|---|---|
| Provider test says 404 or endpoint not found | Configured path does not match local route. | Compare provider URL path with local endpoint instatunnel webhook init --provider stripe --port 3000 --path /webhooks/stripe | Align the provider URL path exactly with your app route. |
| Signature verification fails | Wrong signing secret or body parsing changes raw payload. | Verify provider secret env value Check required signature header | Use raw request body for verification and provider-specific secret/header mapping. |
| Duplicate webhook side effects | Provider retries and no idempotency guard in app logic. | Inspect repeated event IDs in logs | Store processed event IDs and ignore already-processed events. |
| Provider reports timeout / 5xx | Local handler too slow or throws errors under load. | Monitor local app logs and tunnel logs instatunnel --logs | Return fast 2xx, move heavy work async, and handle retries safely. |
| No webhook events are arriving | Wrong environment (test vs live), paused endpoint, or stale URL. | Send provider test event Validate current subdomain URL | Use fixed subdomain, correct provider environment, and re-save endpoint URL. |
Copy-ready command pack
npm install -g instatunnel@latest
instatunnel doctor --mcp
instatunnel webhook init --provider stripe --port 3000 --path /webhooks/stripe
instatunnel webhook verify --provider stripe --secret-env STRIPE_WEBHOOK_SECRET
instatunnel webhook test --provider stripe
FAQ
Should I start with transport v1 or v2 for MCP?
Start with v1 for maximum compatibility. Use v2 only when your MCP client/server requires streaming behavior (Streamable HTTP or long-lived responses).
What is the fastest first check when MCP fails?
Run instatunnel doctor --mcp. It checks config, DNS, API health, auth profile, and MCP readiness in one pass.
Do webhook providers require a stable URL?
Yes. Use a fixed subdomain in your tunnel command so provider dashboards keep a stable endpoint URL.
Why do signature verification errors happen most often?
The wrong secret value, wrong raw-body handling, or using the wrong header key for that provider are the most common causes.
How do I avoid duplicate webhook side effects?
Use idempotency with provider event IDs and store processed IDs so retries do not re-apply business actions.
Can I use local stdio MCP servers with Authorization headers?
No. Local stdio MCP servers do not use HTTP headers. Authorization headers are only relevant for remote HTTP MCP endpoints.