mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
Enrico Toniato
c6043e4d05
* fix: use hosted WebSocket tunnel relay * fix: reattach tunnels across relay deploys * fix: negotiate tunnel keepalive support * refactor: remove spinner state and improve loading indicators in ViewRenderer and MCP Apps components
82 lines
3.6 KiB
Plaintext
82 lines
3.6 KiB
Plaintext
---
|
|
title: "MCP Server Tunneling"
|
|
description: "Expose a local MCP server through a public /mcp URL for testing in ChatGPT, Claude, and other remote MCP clients."
|
|
icon: "train-front-tunnel"
|
|
---
|
|
|
|
Use a tunnel when ChatGPT, Claude, or another remote MCP client needs to reach a server running on your machine. The tunnel gives you a public HTTPS URL that forwards to your local MCP endpoint.
|
|
|
|
With `mcp-use`, start the server with `--tunnel`, then copy the printed `Tunnel` URL. The URL you give to clients must include `/mcp`.
|
|
|
|
```text
|
|
https://<adjective>-<color>.tunnel.mcp-use.run/mcp
|
|
```
|
|
|
|
Keep the terminal process running while you test. The public URL stops working when the process exits.
|
|
|
|
With `mcp-use dev --tunnel` or `mcp-use start --tunnel`, the framework connects directly to the relay over WebSocket. It does not install or execute a native tunnel binary or a separate tunnel package. If the relay connection drops while the command is still running, the tunnel reconnects automatically and reuses the same identifier when possible.
|
|
|
|
The relay forwards both HTTP requests and WebSocket upgrades. In development, MCP App views loaded from the public tunnel keep Vite HMR: editing a local view updates the remote Inspector or client without restarting the tunnel.
|
|
|
|
## Start a tunnel with mcp-use
|
|
|
|
Use `mcp-use dev --tunnel` while you are developing:
|
|
|
|
```bash
|
|
mcp-use dev --tunnel
|
|
```
|
|
|
|
Use `mcp-use start --tunnel` when you want to test the built server:
|
|
|
|
```bash
|
|
mcp-use build
|
|
mcp-use start --port 3000 --tunnel
|
|
```
|
|
|
|
After the production server binds, successful output includes the local and public MCP endpoints:
|
|
|
|
```text
|
|
[mcp-use] starting tunnel for port 3000…
|
|
mcp-use server running at http://localhost:3000/mcp
|
|
mcp-use public MCP URL: https://proper-black.tunnel.mcp-use.run/mcp
|
|
```
|
|
|
|
Copy the value after `mcp-use public MCP URL:` into your remote MCP client. Do not copy only the tunnel origin; the client URL must end with `/mcp`.
|
|
|
|
## Verify the tunnel
|
|
|
|
Verify the public URL with the `mcp-use client` CLI:
|
|
|
|
```bash
|
|
npx mcp-use client connect tunnel-test https://proper-black.tunnel.mcp-use.run/mcp
|
|
npx mcp-use client tunnel-test tools list
|
|
```
|
|
|
|
The `connect` command performs the MCP handshake and saves the tunnel under the name `tunnel-test`. The `tools list` command should print the tools exposed by your local server. If the server uses OAuth or bearer authentication, complete the client authentication flow or pass the required auth option before testing tools.
|
|
|
|
## Stop the tunnel
|
|
|
|
Press `Ctrl+C` in the terminal running the tunnel.
|
|
|
|
When you started the tunnel with `mcp-use dev --tunnel` or `mcp-use start --tunnel`, stopping the command stops both the local server process and the tunnel.
|
|
|
|
## Lifetime and limits
|
|
|
|
Tunnels are for local testing before deployment:
|
|
|
|
- The tunnel is active only while the command is running.
|
|
- With `mcp-use dev --tunnel` or `mcp-use start --tunnel`, a dropped tunnel registration is re-established automatically while the command runs.
|
|
- Reservations that never connect expire after 5 minutes.
|
|
- Connected tunnels expire after 24 hours.
|
|
- Inactive tunnels are cleaned up after 1 hour without activity.
|
|
- Each source IP can create up to 10 tunnels per hour.
|
|
- Each source IP can have up to 5 active tunnels at a time.
|
|
|
|
For a stable public URL, deploy the server instead of relying on a local tunnel.
|
|
|
|
## Next steps
|
|
|
|
- Use the [TypeScript quickstart](/typescript/getting-started/quickstart) to create a local MCP server.
|
|
- Use [Build your first MCP App](/typescript/mcp-apps/quickstart) to test widgets in a remote client.
|
|
- Use [Deploy to Manufact Cloud](/typescript/server/deployment/mcp-use) when you are ready for a hosted MCP endpoint.
|