Tunneling with ngrok

Some MCP integrations cannot use localhost. ChatGPT Developer Mode runs in the browser and requires a remote HTTPS URL. OpenClaw and Claude Cowork may need to reach PiecesOS from another machine. ngrok creates a public HTTPS URL that forwards traffic to your local PiecesOS instance. The tunnel is active only while ngrok is running, and ngrok handles TLS certificates automatically.

Exposing PiecesOS publicly via ngrok should only be used when required. For local-only integrations (Cursor, VS Code, Claude Desktop on the same machine), use localhost directly.

Prerequisites

PiecesOS must be installed and running on the machine where you will run ngrok. Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu). 
<pos-download-guide />
Sign up at [ngrok.com](https://ngrok.com) and get your [auth token](https://dashboard.ngrok.com/get-started/your-authtoken) from the dashboard.

Installing ngrok

Install with Homebrew: 
```bash
brew install ngrok
```
Install via the [Windows App Store](https://apps.microsoft.com/detail/9mvs1j51gmk6) or [download directly](https://ngrok.com/download). On Debian/Ubuntu: 
```bash
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update \
  && sudo apt install ngrok
```

Verify the installation:

ngrok help

Setting Up the Tunnel

Add your auth token so ngrok can create tunnels: 
```bash
ngrok config add-authtoken YOUR_AUTH_TOKEN
```

Replace `YOUR_AUTH_TOKEN` with the token from your [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).
PiecesOS typically runs on port **39300**. To find yours: open the **PiecesOS Quick Menu** (system tray or menu bar) → expand **Model Context Protocol (MCP) Servers** → copy the endpoint (it includes the port). You can also find it in Pieces Desktop under **Settings** → **Model Context Protocol (MCP)**. Ensure PiecesOS is running, then: 
```bash
ngrok http 39300
```

Replace `39300` with your actual port if different. ngrok will display a forwarding URL like `https://abc123.ngrok-free.app`. Copy the **HTTPS** URL.

MCP Endpoint URLs

Append the correct path to your ngrok URL:

Endpoint Path Use for
Streamable HTTP /model_context_protocol/2025-03-26/mcp ChatGPT, Claude Cowork Connectors UI
SSE /model_context_protocol/2024-11-05/sse MCP Bridge, OpenClaw remote

Example: if ngrok shows https://abc123.ngrok-free.app, use https://abc123.ngrok-free.app/model_context_protocol/2025-03-26/mcp for ChatGPT or https://abc123.ngrok-free.app/model_context_protocol/2024-11-05/sse for MCP Bridge.

Configuring Your MCP Client

ChatGPT Developer Mode

  1. Open chatgpt.com → Settings → Connectors.
  2. Click Create and add a new connector.
  3. Set MCP Server URL to: https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp
  4. Save. The tunnel must be running whenever you use ChatGPT with Pieces.

See ChatGPT Developer Mode integration for full setup.

Claude Cowork (Connectors UI)

  1. Open Claude Desktop → Settings → Connectors.
  2. Click Add custom connector.
  3. Enter: https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp
  4. Save and restart Claude Desktop.

See Claude Cowork integration for full setup.

OpenClaw (Remote)

Install mcp-remote globally (npm install -g mcp-remote@0.1.38), then edit ~/.openclaw/workspace/config/mcporter.json:

{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}

See OpenClaw integration for full setup.

Tips & Troubleshooting

The tunnel is active only while ngrok http 39300 is running. Start ngrok when you need remote access, or keep it running in a dedicated terminal for regular use.

Free ngrok accounts get a random subdomain each time you start a tunnel. If the URL changes, update the MCP Server URL in your client (ChatGPT: Settings → Connectors; Claude Cowork: Settings → Connectors; OpenClaw: edit `~/.openclaw/workspace/config/mcporter.json`).

Troubleshooting

  1. Tunnel not connecting — Ensure PiecesOS is running and listening on the port. Test locally: curl http://localhost:39300/.well-known/version

  2. Wrong port — Use the port from the PiecesOS Quick Menu or Settings → Model Context Protocol (MCP). It may not be 39300.

  3. URL not accessible — Verify ngrok is running and the HTTPS URL loads in a browser. Free plans may show an ngrok interstitial page on first visit; that's normal.

  4. Subdirectory paths — Use the exact paths: /model_context_protocol/2025-03-26/mcp or /model_context_protocol/2024-11-05/sse. Paths like /functions/v1/mcp do not work.

  5. Connection refused — Restart PiecesOS and ngrok. Ensure no firewall is blocking the port.

Security

ngrok exposes PiecesOS to the internet—use it only when required. Keep your ngrok auth token private. For private network access, consider Tailscale or a VPN instead of a public tunnel.

Next Steps

Configure your MCP client with the ngrok URL: ChatGPT Developer Mode, Claude Cowork, OpenClaw, or MCP Bridge.