Uso de MCP

Use MCP mode to expose local MCP endpoints for remote clients. MCP mode is available on Pro and Business plans.

Plan requirement: MCP mode requires a logged-in API key on Pro or Business.

1. Install CLI

$ npm install -g instatunnel

2. Authenticate (new vs existing users)

New user

$ instatunnel auth login -e you@example.com

# Verify email from inbox and copy API key from verification page

$ instatunnel auth set-key "it_your_api_key"

Existing user

$ instatunnel auth show-key --reveal --copy

# If key is not saved locally:

$ instatunnel auth login -e you@example.com

# Use recovery email, then save the new/current key:

$ instatunnel auth set-key "it_your_api_key"

$ Set-Clipboard "it_your_api_key" # Windows PowerShell helper

$ instatunnel auth set-key "$(Get-Clipboard)"

$ pbpaste | xargs -I {} instatunnel auth set-key "{}" # macOS

$ xclip -o -selection clipboard | xargs -I {} instatunnel auth set-key "{}" # Linux

2a. Use Dashboard MCP Setup Wizard (recommended)

Prefer a guided flow? Open your dashboard and use MCP Setup Wizard v2 inside CLI Updates, MCP, and 2026 Best Practices. It helps you avoid config mistakes and generates copy-ready commands + JSON.

Checks MCP plan eligibility before setup.
Builds the exact instatunnel ... --mcp --transport v2 command using your port and subdomain.
Generates one-click JSON for VS Code, Cursor, Claude Desktop, Windsurf, Codex, and Gemini Antigravity.

3. Start MCP tunnel (v1 default)

v1 is the default transport. It is the most compatible option and best for standard HTTP forwarding and webhook-style traffic.

$ instatunnel 8787 --mcp

$ instatunnel 8787 --mcp --subdomain my-mcp

4. Use streaming transport v2 when needed

Use v2 when you need streaming behavior (MCP Streamable HTTP, long-lived tool responses, or server push-like flows). If unsure, start with v1 and switch to v2 only for streaming clients.

$ instatunnel 8787 --mcp --transport v2

$ instatunnel 8787 --mcp --transport v2 --subdomain my-mcp

Compatibility: --transport v2 requires newer InstaTunnel CLI versions (1.1.7+). Recommended update: npm install -g instatunnel@latest.

5. Optional MCP token header (staged rollout)

InstaTunnel supports an MCP token header for defense in depth. During the current staged rollout, your workspace may run in warn mode first and enforce mode later.

$ export INSTATUNNEL_MCP_TOKEN="your-shared-secret"

$ instatunnel 8787 --mcp --transport v2

5a. Generate YOUR_MCP_TOKEN

Generate a strong token and use it as YOUR_MCP_TOKEN in MCP JSON Authorization headers.

$ 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

6. Configure your MCP client/server

Use the generated HTTPS URL in your MCP client configuration and point it to the path your local MCP server expects.

https://your-subdomain.instatunnel.my

6a. Do you need Authorization headers?

No for local stdio MCP servers. Headers are not used there.
No if your remote MCP server does not enforce auth.
Yes only when your MCP server expects a bearer token (recommended on public endpoints).
This applies to VS Code, Cursor, Claude Desktop, Windsurf, Codex, and Gemini Antigravity: client itself does not force bearer auth; server policy decides.

7. One-click MCP config generator

Generate and copy ready-to-use JSON 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

Loading MCP setup...

Notes

v1 remains the default transport for compatibility.
If unsure, start with v1.
Use v2 for MCP Streamable HTTP and long streaming responses.
--transport v2 requires CLI 1.1.7+; keep updated with npm install -g instatunnel@latest.
MCP tunnels have stricter protections, including MCP-specific rate limits.
Use instatunnel --stats for account usage and instatunnel --logs for request-log polling.
Use authentication and avoid exposing sensitive tools publicly.

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

Loading MCP FAQ...

Documentacion

Uso de MCP

1. Install CLI

2. Authenticate (new vs existing users)

2a. Use Dashboard MCP Setup Wizard (recommended)

3. Start MCP tunnel (v1 default)

4. Use streaming transport v2 when needed

5. Optional MCP token header (staged rollout)

5a. Generate YOUR_MCP_TOKEN

6. Configure your MCP client/server

6a. Do you need Authorization headers?

7. One-click MCP config generator

One-Click MCP Config Generator

Notes

MCP FAQ (Localhost, Webhooks, IDE Setup)

Necesitas una ruta rapida?

One-Click MCP Config Generator

MCP FAQ (Localhost, Webhooks, IDE Setup)