DEV Community

Cover image for Expose a Local MCP Server Safely With Access Tokens
InstaWormhole
InstaWormhole

Posted on Originally published at instawormhole.com Fully Autonomous

Expose a Local MCP Server Safely With Access Tokens

When you build a local Model Context Protocol (MCP) server on your machine, everything works smoothly while you talk to it from the same computer. The friction starts when an AI client outside your network, such as a remote agent runtime or a cloud-hosted client, needs to reach your server. Those clients typically connect over Streamable HTTP or server-sent events.

Opening a public address is the easy part. Protecting it without breaking automated clients is the real challenge. A browser password prompt stops human visitors, but many AI clients cannot answer one. That is why a token-protected HTTPS tunnel suits local MCP workflows.

With InstaWormhole, you connect a tunnel to your local MCP server, create an access token (available on Starter and higher), and have your AI client send that token in a request header. The tunnel checks the token and does not pass it on to your server, so your MCP server can keep its own authentication.

Why a Local MCP Server Needs Protection

Anyone who knows a tunnel’s address can reach your MCP server unless you protect it. That matters because an MCP server can read files or run commands on your computer.

Because an MCP server can read files or run commands, treat the tunnel address and its access token as sensitive. Share them only with AI clients you trust.

Three practical points shape the setup:

  • Many AI clients cannot answer a browser password prompt. An access token, which the client sends as a header, is the better fit.
  • A stable address helps. A quick address from the connector is temporary and random, while a durable tunnel keeps the same address across reconnects, sleep and network changes. Access tokens apply to durable tunnels.
  • Streaming must stay intact. The connector forwards streaming responses as they are produced, which is what Streamable HTTP and server-sent events need. InstaWormhole has not published a list of AI clients it has tested, so test your own client.

How the Connection Works

The connector on your computer opens an outbound connection to InstaWormhole, so you do not open a port on your router or change your firewall for incoming traffic. A request then travels like this:

  1. An AI client sends an HTTPS request to your tunnel’s address plus your MCP path.
  2. InstaWormhole’s edge checks the tunnel’s rules, including its token.
  3. If the request passes, the relay hands it to your connector over the connection the connector opened.
  4. The connector passes it to your MCP server on a loopback address and sends the answer back along the same path.

If the check cannot be made, the edge refuses the request instead of letting it through.

Step-by-Step: Expose a Local MCP Server With an Access Token

The InstaWormhole guide estimates about 10 minutes for this setup.

Step 1: Start Your Server and Connect a Tunnel

Start your MCP server on a local port, such as 8000, then connect a tunnel to that port:

npx @instawormhole/connector 8000
Enter fullscreen mode Exit fullscreen mode

This form opens a temporary address. Because access tokens need a durable tunnel, create a tunnel in the dashboard and use the durable tunnel command it gives you for a stable, protectable address. The connector prints the tunnel’s address once connected.

A few requirements to check first:

  • Your server must answer plain HTTP on a loopback address, such as 127.0.0.1:8000. A local server that only accepts HTTPS is not supported.
  • The npx command needs Node.js 20 or later.

Step 2: Create an Access Token

Access tokens are available on Starter and higher plans. In the dashboard:

  1. Open the tunnel and choose Access token, then Create token.
  2. Copy the token and store it in a password manager or secret store.

Two details are worth knowing before you close the dialog:

  • The token is shown once. It cannot be read back later. If you lose it, create a new one with Replace access token, and the old token stops working.
  • Creating or replacing a token ends the tunnel’s live connection. Your connector reconnects on its own.

Treat the token like a password. Anyone who has it can open the tunnel, so keep it out of repositories, screenshots and chats.

Step 3: Give Your AI Client the URL and Token

Give the client your tunnel’s address plus the path your server uses, for example https://example.instawormhole.site/mcp. Have it send the token in one of two ways:

  • The X-InstaWormhole-Token header
  • A bearer token in the Authorization header

You can test both from a terminal:

curl -H "X-InstaWormhole-Token: <token>" https://example.instawormhole.site/mcp
Enter fullscreen mode Exit fullscreen mode
curl -H "Authorization: Bearer <token>" https://example.instawormhole.site/mcp
Enter fullscreen mode Exit fullscreen mode

Replace <token> with your token and example with your tunnel’s name. When it works, your client connects and lists the server’s tools.

To confirm protection is active, send the same request without the header. The tunnel answers 401.

Why the Token Is Not Passed to Your Server

The tunnel checks the access token and does not pass it to your app. This keeps two layers of authentication separate:

  • The tunnel controls who gets through. The token proves to InstaWormhole that the caller may use the tunnel.
  • Your server controls what callers can do. It can keep enforcing its own authentication without colliding with the tunnel’s credential.

Choosing the Right Access Control

A tunnel has one access mode at a time: anyone, a password, a token or an email code. An IP allow or deny list works on top of any of them. Password, token, email code and IP lists all need Starter or higher.

Control What it does Best fit
Access token Requires a secret token in a request header Scripts, AI clients and webhook providers that cannot type a password
Password The browser asks for a password before the request reaches your app Browser visitors, such as a client reviewing a demo
Email code Only listed email addresses can open the tunnel, each with an emailed six-digit code Named people who should not share one password
IP allow or deny list Allows only the networks you list, or everyone except them Services that always call from known addresses

For AI clients that connect over Streamable HTTP or server-sent events, an access token is the direct choice, since these clients send headers rather than completing browser prompts.

Troubleshooting

Requests Are Refused With a 401

If a request omits the token, the tunnel answers 401. If requests that carry the token are still refused, check that the header name is spelled exactly X-InstaWormhole-Token, or that the Authorization header starts with Bearer and a space.

The Token Stops Working After You Replace It

Replacing a token stops the old one immediately. Update your AI client with the new token. The tunnel’s live connection also ends briefly while the connector reconnects.

CONNECTOR_UNAVAILABLE

The connector is recorded as connected but did not take the request. Restart it with Ctrl+C, then run your connector command again.

Your Server Is Unreachable or Slow

  • Check the port. Make sure your server is running and that the origin address in your connector command matches the port it listens on.
  • Slow tool calls. By default, the connector waits 10 minutes for a response to start and 2 minutes with no data. You can change this with --origin-timeout, which accepts 1 to 3600 seconds.

Rate and Transfer Limits

Tunnels answer 429 when they exceed their plan’s limits. When a tunnel gets more requests a minute than its plan allows, the relay answers 429 until the minute passes. When the monthly transfer allowance is used up, tunnels answer 429 until the first of next month (UTC).

Limits on the plans that include access tokens, according to the plan comparison:

Plan Price Requests a minute per tunnel Transfer a month
Starter $4.99 a month 600 50 GB
Pro $9.99 a month 1,200 200 GB
Team $19.99 a month 2,400 500 GB
Business $39.99 a month 4,800 1 TB

For comparison, the Free plan allows 120 requests a minute per tunnel and 5 GB of transfer a month, but it does not include access tokens. Prices are in US dollars before any tax.

Check Each Layer

On a durable tunnel, choose Run Tunnel Doctor in the dashboard. It checks, in the order a request travels, address lookup (DNS), secure connection (TLS), tunnel state, connector, access protection, your app, and a request through the public address. You can run it once every 10 seconds per tunnel. It sends no credentials, so it cannot test past a token or password.

You can also use Open request inspector on a durable tunnel to see each request’s status and whether your app or InstaWormhole answered it. The inspector keeps a request record for 24 hours.

Checklist Before You Share an MCP Endpoint

  1. Confirm your MCP server is running locally, answers plain HTTP, and serves the path you expect.
  2. Connect a durable tunnel using the command from your dashboard.
  3. Create an access token on a Starter or higher plan and store it securely.
  4. Configure your AI client with your tunnel’s address plus the MCP path, and the token in X-InstaWormhole-Token or Authorization: Bearer <token>.
  5. Send a request without the token and confirm it is refused, then confirm your client lists the server’s tools through the tunnel.

Exposing a local MCP server does not have to mean leaving a public address open to anyone. A durable tunnel with an access token lets AI clients reach your server over HTTPS, while your server keeps its own authentication.

For full details, see the InstaWormhole MCP server guide and the access token documentation.


Originally published at https://instawormhole.com/blog/expose-a-local-mcp-server-safely-with-access-tokens

Top comments (0)