> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an internal server through a tunnel

> A hands-on walkthrough for reaching an MCP server on your internal network, such as a self-hosted GitLab, through a server tunnel: create the tunnel, list the server's origin, connect a machine with the one-time command that you never run again (one container, no Docker socket), add the server as Reached through a tunnel, assign it to a gateway, and have each user sign in with their own identity.

By the end of this tutorial, an MCP server on your internal network will be reachable through an **MCP Manager** gateway, and each person who uses it will sign in as themselves. Nothing on your network is exposed to the internet, and you open no inbound port.

This tutorial uses a self-hosted GitLab at `https://gitlab.example.internal` as the example. Its MCP endpoint is `https://gitlab.example.internal/api/v4/mcp`.

> [!NOTE]
>
> **Following along with your own server?** Only two values change. Use your server's origin (scheme, host and port) in [Step 1](#step-1-create-a-server-tunnel), and its MCP URL in [Step 3](#step-3-add-the-internal-server). Everything else is the same.

> [!NOTE]
>
> You need four capabilities: **Manage tunnels** for the tunnel, **Basic server management** to add the server, **Basic gateway management** to assign it to a gateway, and **View and export logs** to see the logs at the end. Server tunnels must also be enabled for your workspace. Without that, or without **Manage tunnels**, you won't see the **Tunnels** section. Ask a workspace administrator. See [Who can manage server tunnels](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#who-can-manage-server-tunnels).

## What you'll need

* An MCP Manager workspace and a role with the capabilities above.
* **A Linux machine on your internal network** that your organization controls and that stays on. It must reach the internal server. The tunnel machine sees every credential sent through it, so don't use a personal laptop. See [What the tunnel machine can see](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#what-the-tunnel-machine-can-see).
* **Docker Engine** on that machine, running as root (the standard install). Rootless Docker and Podman aren't supported yet. The machine runs no other server tunnel: one per Docker host.
* **Outbound TCP 443** from that machine to `app.mcpmanager.ai`, `headscale.mcpmanager.ai`, `derp-a.mcpmanager.ai`, `derp-b.mcpmanager.ai`, and Docker Hub's `registry-1.docker.io`, `auth.docker.io` and `production.cloudfront.docker.com`. See [What the tunnel machine needs](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#what-the-tunnel-machine-needs).
* **The internal server's MCP URL.**
* **For each person who will sign in:** a browser that can reach the server's sign-in page, for example on your office network or VPN.

## Step 1: Create a server tunnel

**1. Open Tunnels**

Open the **Tunnels** section in MCP Manager.

**2. Create the tunnel**

Select **Create server tunnel**. In **Tunnel name**, name it after the network it reaches, for example `Office network`. Under **Allowed destinations**, list the origins it may reach, one per line, for example `https://gitlab.example.internal`. An origin is the scheme, host and port only, with no path. Select **Create tunnel**, and the tunnel's page opens.

> [!TIP]
>
> **Your own server:** if it signs users in through a separate host, such as your own identity provider, add that origin too. Every request through the tunnel, including each step of the sign-in, must go to an allowed origin.

## Step 2: Connect a machine

**1. Open Connect a machine**

On the tunnel's page, select **Connect a machine**. The window lists the tunnel's allowed destinations, and MCP Manager makes the command and shows it right away.

If the window says that no agent release is available yet, MCP Manager has to publish one before it can give you a command. Try again later.

**2. Check the allowed destinations**

Make sure `https://gitlab.example.internal` is on the list. If it isn't, select **Edit**, add it, and select **Save and generate command**. MCP Manager saves the list and makes a new command.

> [!WARNING]
>
> Check the list before you run the command. The command caps where this machine may send requests, in its `MCPM_TUNNEL_ALLOWED_ORIGINS` value, and MCP Manager fills that value in from this list. To reach an origin you add later, the machine needs a new command. See [Limit destinations on the machine itself](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#limit-destinations-on-the-machine-itself).

**3. Copy the command**

Leave **Docker (default)** selected for Docker Desktop, for Docker inside a VM, and for servers elsewhere on your network. If the machine is a Linux host with Docker Engine and your server runs on that same machine, choose **Docker Engine on Linux (host network)** under **Not working? Try another variation**, so the tunnel reaches the server at `localhost`.

Select **Copy command**. Copy it before you close the window, because MCP Manager shows it once. It can be used once, and it expires after 24 hours. For a fresh one, select **re-generate command** next to the expiry time.

**4. Run it on the machine**

Run the command on the machine in your network. MCP Manager fills in every value, so it looks like this with your own:

```bash terminal theme={null}
docker run -d --name mcpm-server-tunnel --restart unless-stopped --cap-drop ALL --cap-add SETUID --cap-add SETGID --security-opt no-new-privileges --read-only --pids-limit <P> --memory <M> --memory-swap <M> -v mcpm-tunnel-<id>:/var/lib/mcpm --add-host host.docker.internal:host-gateway -e "MCPM_TUNNEL_ALLOWED_ORIGINS=<origins>" mcpmanager/tunnel@sha256:<digest> enroll server_tunnel <token>
```

The command starts one container in the background and returns. The container gets no Docker socket and no folder from your host, and everything it's allowed to do is in that line. See [Every privilege the tunnel gets is in the command](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#every-privilege-the-tunnel-gets-is-in-the-command).

On its first start, the container makes the machine's key, downloads the current signed release, checks it, and starts the worker that connects to your tunnel.

The container is always named `mcpm-server-tunnel`, so a host runs one server tunnel machine. Running the command again, or replacing a machine on a host that already runs one? Remove the old container first. The window shows this command above the install command:

```bash terminal theme={null}
docker rm -f mcpm-server-tunnel
```

Removing the container disconnects that machine from its tunnel. If you're replacing a machine, also terminate the old one in the tunnel's **Machines** list, so MCP Manager stops accepting its key.

**5. Wait for the machine to come online**

Leave the window open. It checks the tunnel every few seconds for 10 minutes. When the new machine is online, usually within a minute or two, the window closes by itself and a **Tunnel is available.** message appears. The machine shows on your tunnel, and your workspace gets an alert, **A machine joined a server tunnel**. To check right away, or after 10 minutes, select **Check connection**.

> [!WARNING]
>
> If the machine doesn't come online, **Check connection** tells you whether it enrolled. To see why, read the container's log on the machine:
>
> ```bash terminal theme={null}
> docker logs mcpm-server-tunnel --tail 200
> ```
>
> A message that the command was already used or has expired means you need a new command from **Connect a machine**. A message that a host cannot be reached means a firewall or proxy is blocking it. See [What the tunnel machine needs](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#what-the-tunnel-machine-needs). For a worker that stays in **Joining**, see [A worker stays in Joining](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#a-worker-stays-in-joining).

> [!NOTE]
>
> You run this command once. The container restarts on its own after a reboot, and the tunnel updates itself with signed releases. You never run the command again to stay current or secure. See [Automatic updates with no downtime](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#automatic-updates-with-no-downtime).

## Step 3: Add the internal server

**1. Enter the server's URL**

Go to [MCP Servers](https://app.mcpmanager.ai/settings/servers), click **Add**, choose **Remote**, and enter the URL: `https://gitlab.example.internal/api/v4/mcp`.

Shortcut: **Add a server through it**, in the **Tunnel is available.** message, opens this window with `Office network` already chosen. The message stays until you close it. **Add** in **Servers reached through this tunnel**, on the tunnel's page, does the same.

**2. Route it through the tunnel**

Before you select **Continue**, open **Reach this server through a tunnel (optional)**, turn on **Reached through a tunnel**, and choose `Office network`. You can't change this after **Continue**.

The window shows that `https://gitlab.example.internal` is already in the tunnel's allowed destinations. For a server whose origin isn't on the list yet, a switch to add it is on by default. A machine connected before that needs a new command to reach the new origin.

**3. Finish adding the server**

Select **Continue**, check the **Server name**, and select **Continue** again. MCP Manager connects to the server through the tunnel. If it asks you to sign in, select **Authenticate now** to sign in as yourself, or **Do it later**.

> [!NOTE]
>
> From now on, MCP Manager sends this server's traffic only through `Office network`. It never calls the URL directly, even when the tunnel is down.

## Step 4: Assign the server to a gateway

**1. Assign it**

Go to [Gateways](https://app.mcpmanager.ai/settings/gateways), open the gateway your team uses, and on its **Servers** tab click **Assign a server**. Select the GitLab server. Its identity setup opens.

**2. Choose per-user identity**

Under **Identity Scheme**, select **Each user uses their own identity**, so each person signs in to GitLab as themselves. See [Identity Controls](https://docs.mcpmanager.ai/features/identity-controls.md).

## Step 5: Each person signs in as themselves

**1. Connect the gateway**

Each person connects the gateway in their AI client, as in [Connect your AI client to a gateway](https://docs.mcpmanager.ai/tutorials/connect-your-ai-client.md). MCP Manager shows **Connect to GitLab**.

**2. Authorize**

They select **Authenticate with GitLab**, or **Add new identity** if they already have identities. GitLab's sign-in and consent screen opens in **their** browser, so that browser must reach `https://gitlab.example.internal`. If it can't, they connect to the VPN and try again.

Everything else in the sign-in, such as the token exchange, goes through the tunnel machine.

**3. Call a tool**

In the AI client, ask for something that uses GitLab:

```text theme={null}
List my open merge requests in GitLab.
```

The request goes from the client to the MCP Manager gateway, through the tunnel to the machine on your network, and on to GitLab, signed in as that person.

**4. Find the call in your logs**

Go to [Logs](https://app.mcpmanager.ai/settings/logging/logs) and open the newest `tools/call` entry. It shows who made the call, through which gateway, on the GitLab server. GitLab's own audit log shows the same person.

> [!WARNING]
>
> If a call fails, the error links to what to do. **Tunnel unavailable** means no machine on the tunnel is online: see [Tunnel unavailable](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#tunnel-unavailable). A refused destination means an origin is missing from the list: see [Allowed destinations](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#allowed-destinations).

> [!TIP]
>
> An internal server is now behind your gateway. Each person signs in to it as themselves, every call is governed and logged, and your network accepts no inbound connection. MCP Manager keeps the tunnel machine up to date on its own, so you never run the install command again.

## What's next

* Connect a second machine to the tunnel, so one machine going down doesn't stop traffic. See [More than one machine for failover](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#more-than-one-machine-for-failover).
* Check each machine's version and update status in the **Tunnels** section. The status is read-only, and **Waiting its turn** is normal. See [What the Tunnels section shows about updates](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#what-the-tunnels-section-shows-about-updates).
* Add more internal servers on the same network to the same tunnel. When you add a server's origin to the allowed destinations, each machine connected before that needs a new command to reach it. See [Limit destinations on the machine itself](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md#limit-destinations-on-the-machine-itself).
* Add a guardrail to the gateway in [Add your first gateway rule](https://docs.mcpmanager.ai/tutorials/first-gateway-rule.md).

## Further reading

> [card] [Server Tunnels](https://docs.mcpmanager.ai/mcp-gateway-concepts/mcp-servers/server-tunnels.md)
>
> How a server tunnel works, what runs in the container, how updates run, and terminating a machine.

> [card] [Identity Controls](https://docs.mcpmanager.ai/features/identity-controls.md)
>
> Per-user and shared identity, and what each looks like for the people who connect.

> [card] [Connect a workstation MCP server](https://docs.mcpmanager.ai/tutorials/connect-a-workstation-server.md)
>
> Connect a server that runs on your own machine instead.

> [card] [Capabilities reference](https://docs.mcpmanager.ai/deployment/rbac-and-roles/capabilities.md)
>
> The capabilities that gate server tunnels and gateways.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.