CLI-Flags Guide

Vollstandige Referenz der InstaTunnel CLI-Kommandos inklusive MCP-Setup und produktionssicherer Nutzung.

Install, Verify, Update

npm install -g instatunnel

instatunnel --version

npm install -g instatunnel@latest

npm view instatunnel version

For MCP and webhook failures, use the troubleshooting matrix: /docs/troubleshooting

MCP User Flow (Pro/Business)

New user

instatunnel auth login -e you@example.com
Verify email and copy API key from the verification page.
instatunnel auth set-key "it_your_api_key"

Existing user

instatunnel auth show-key --reveal --copy
If no key is saved locally: instatunnel auth login -e you@example.com (recovery email flow).
After recovery/reset, save key again: instatunnel auth set-key "it_your_api_key"

Start MCP tunnel

Start with default v1 (most compatible): instatunnel 8787 --mcp --subdomain mymcp
Switch to v2 only for streaming MCP clients: instatunnel 8787 --mcp --transport v2 --subdomain mymcp
Use endpoint: https://mymcp.instatunnel.my/mcp

Transport guidance: if unsure, start with v1. Use v2 for MCP Streamable HTTP and long-lived streaming responses. --transport v2 requires newer CLI versions (1.1.7+). Update with npm install -g instatunnel@latest.

Prefer guided setup?

Use MCP Setup Wizard v2 from your dashboard under CLI Updates, MCP, and 2026 Best Practices. It generates the tunnel command and client JSON based on your inputs.

Open: /dashboard - then use the wizard step flow for port, subdomain, token header, and JSON copy.

Generate `YOUR_MCP_TOKEN`

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | Set-Clipboard # Windows

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | pbcopy # macOS

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | xclip -selection clipboard # Linux

Use this token in MCP JSON: "Authorization": "Bearer YOUR_MCP_TOKEN".

When is Authorization required?

Local stdio MCP servers: not required (headers not used).
Remote MCP over HTTP: only required if your MCP server enforces token auth.
This rule is the same for VS Code, Cursor, Claude Desktop, Windsurf, Codex, and Gemini Antigravity.

One-Click MCP Config Generator

Generate IDE-ready JSON for VS Code, Cursor, Claude Desktop, Windsurf, Codex, and Gemini Antigravity with endpoint and token header.

Tunnel subdomainMCP token

MCP Endpoint

https://your-subdomain.instatunnel.my/mcp

Target: .vscode/mcp.json (workspace)

{
  "mcpServers": {
    "instatunnel-remote": {
      "type": "streamable-http",
      "url": "https://your-subdomain.instatunnel.my/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

headers.Authorization is not required by MCP clients by default. Add it only when your MCP server expects bearer-token auth. For local stdio MCP servers, headers are not used.

Token helper

Generate a strong token, paste it into YOUR_MCP_TOKEN, and use the same value in your local MCP server auth.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | Set-Clipboard

Optional staged security header: set INSTATUNNEL_MCP_TOKEN to send X-InstaTunnel-MCP-Token in addition to your MCP server bearer token.

Flags Reference

Flag	Purpose	Example
`--subdomain, -s`	Custom subdomain	`instatunnel 3000 -s myapp`
`--domain, -d`	Custom domain (Pro/Business)	`instatunnel 3000 -d app.example.com`
`--region, -r`	Region (current deployment supports only `us`)	`instatunnel 3000 -r us`
`--password`	Password-protect tunnel	`instatunnel 3000 --password demo123`
`--auth`	Basic auth	`instatunnel 3000 --auth user:pass`
`--qr`	Show QR code	`instatunnel 3000 --qr`
`--mcp`	MCP mode (Pro/Business)	`instatunnel 8787 --mcp`
`--transport`	`v1` default (compat/webhooks), `v2` for streaming MCP (`1.1.7+`)	`instatunnel 8787 --mcp --transport v2`
`--list`	List tunnels (auth)	`instatunnel --list`
`--kill`	Stop by subdomain (auth)	`instatunnel --kill myapp`
`--logs`	Poll request logs (Pro/Business)	`instatunnel --logs`
`--stats`	Real 30-day usage summary (auth)	`instatunnel --stats`
`--react / --next / --laravel`	Framework shortcuts	`instatunnel --react`
`auth show-key`	Show saved API key (masked by default)	`instatunnel auth show-key --reveal --copy`
`--share`	Share text templates	`instatunnel --share`

Real-World Usage Patterns

# Webhook testing

instatunnel 3000 -s stripe-webhook --auth qa:pass123

# Frontend + API in parallel terminals

instatunnel 3000 -s frontend-demo

instatunnel 8000 -s api-demo

# MCP endpoint with streaming

instatunnel auth set-key "it_your_api_key"

instatunnel auth show-key

instatunnel 8787 --mcp --transport v2 -s mcp-demo

Priority Use Cases: OAuth + Team QA

OAuth callback testing

Start your app locally on port 3000.
Run instatunnel 3000 --subdomain oauth-dev.
Set provider redirect URI to https://oauth-dev.instatunnel.my/auth/callback.
Complete login flow and inspect requests with instatunnel --logs.

Keep one stable subdomain per environment to avoid changing redirect URIs repeatedly.

Team QA / demo links

Start protected tunnel: instatunnel 3000 --subdomain acme-qa --auth qa:review2026 --qr
Share URL and credentials to reviewers.
Use instatunnel --share for copy-ready announcement text.
Rotate credentials and stop tunnel after review with Ctrl+C or instatunnel --kill acme-qa.

For client-facing demos, prefer explicit auth and stable subdomain naming.

Release Notes

Latest release: 1.1.16

Startup update checks now notify users when a newer npm version is available.
Update prompt includes direct command: npm install -g instatunnel@latest.
Added auth show-key to view saved API key (masked).
Added auth show-key --reveal --copy for explicit recovery and clipboard copy.
Webhook helper defaults improved for Stripe and Twilio endpoint paths.
CLI links corrected (docs, webhook guide, support email).
Real --stats from analytics API.
Real --logs request-log polling.
--region fail-fast validation for unsupported regions.

Full changelog on GitHub: CHANGELOG.md

MCP FAQ (Localhost, Webhooks, IDE Setup)

Common setup and troubleshooting questions for VS Code, Cursor, Claude Desktop, Windsurf, Codex, and Gemini Antigravity.

Do VS Code, Cursor, Claude Desktop, Windsurf, Codex, or Gemini Antigravity require Authorization headers by default?

No. The client usually does not force bearer headers. Add "Authorization": "Bearer YOUR_MCP_TOKEN" only if your remote MCP server enforces token auth. For local stdio MCP servers, headers are not used.

Which endpoint should I use with InstaTunnel?

Use: https://YOUR-SUBDOMAIN.instatunnel.my/mcp. Start your local MCP server first, then run: instatunnel 8787 --mcp --transport v2 --subdomain YOUR-SUBDOMAIN.

What is the difference between local stdio MCP and remote HTTP MCP?

Local stdio is process-to-process on your machine, with no public URL. Remote HTTP MCP is reachable via URL and is required when an IDE or agent needs to access your MCP server from another network context.

Why do I get "failed to reach local server localhost:8787"?

InstaTunnel can reach the public tunnel, but your local app is not listening on the forwarded port. Start your MCP server locally on the same port (for example 8787) and retry.

Can I use this for localhost sharing and webhook testing?

Yes. For generic webhook testing, use normal HTTP tunnels (for example instatunnel 3000 --subdomain webhook-demo). For MCP tools, use MCP mode with --mcp --transport v2 and the /mcp endpoint.

Which transport should I use: v1 or v2?

v1 is default and most compatible, so start there if you are unsure. Use v2 when you need Streamable HTTP behavior (long-lived streaming/tool responses). Recommended: instatunnel 8787 --mcp --transport v2. Note: --transport v2 requires newer CLI versions (1.1.7+). Update with npm install -g instatunnel@latest.

Why do I get "MCP mode is available on Pro and Business plans"?

MCP mode is gated by plan. Upgrade to Pro/Business, then rerun your command with the same saved API key.

Where do I configure MCP clients?

Use each client's MCP settings area. The JSON shape from the generator works for common MCP clients. For Codex, you can also register MCP servers via codex mcp add.

Official references