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.
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
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.