# Mcp Launch

> Self-hosted Docker stack to run MCP servers locally and expose them securely to any AI agent over the internet.

- **Type:** MCP server
- **Install:** `agentstack add mcp-oxcodexo-mcp-launch`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [oxcodexo](https://agentstack.voostack.com/s/oxcodexo)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [oxcodexo](https://github.com/oxcodexo)
- **Source:** https://github.com/oxcodexo/mcp-launch

## Install

```sh
agentstack add mcp-oxcodexo-mcp-launch
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Launch

A self-hosted, Docker-based stack for running MCP servers on your laptop and exposing them securely to any AI agent over the internet. New MCP servers plug in by adding a service and a single route — no changes to ngrok, Caddy, or any other part of the infrastructure.

## How It Works

```
AI Agent
  └── https:////mcp
        └── ngrok  →  caddy :9876
                       ├── /sandbox/*  →  sandbox-mcp:9002
                       ├── /my-tool/*  →  my-tool-mcp:9003
                       └── ...more as needed
```

Each MCP server runs as an isolated Docker container. Caddy sits in front and routes by path prefix. ngrok gives every MCP a stable public HTTPS URL. A shared bearer token protects all endpoints — validated by `supergateway` on every incoming request, before any tool is executed.

## Prerequisites

- **Docker** — [Install Docker](https://docs.docker.com/get-docker/)
- **Docker Compose v2** — included with Docker Desktop; on Linux run `docker compose version` to confirm (requires v2.x)
- **ngrok account** — [Sign up free](https://ngrok.com). You need:
  - An auth token (from the [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken))
  - A static domain (one free static domain per account — create yours at [ngrok dashboard → Domains](https://dashboard.ngrok.com/domains))

## Project Structure

```
mcp-launch/
├── docker/
│   └── sandbox/
│       └── Dockerfile        ← custom image for the sandbox MCP
├── docker-compose.yml        ← all services: caddy, ngrok, MCP servers
├── Caddyfile                 ← routing rules, one route per MCP server
├── .env                      ← secrets (gitignored)
├── .env.example              ← safe template to commit
├── .gitignore
└── README.md
```

## Infrastructure Services

These run once and never change when you add more MCPs:

| Service | Port | Description |
|---|---|---|
| `caddy` | 9876 | Reverse proxy — routes requests by path prefix to the right MCP container |
| `ngrok` | 4040 | Exposes Caddy to the internet at a stable HTTPS URL |

## MCP Servers

Currently included:

| Service | Endpoint | Description |
|---|---|---|
| `sandbox-mcp` | `/sandbox/mcp` | A self-contained Linux environment the agent can freely operate in — run shell commands, read and write files, execute scripts, and use installed tools. Isolated from the host OS; only the mounted `/workspace` directory is accessible. |

## Adding a New MCP Server

The stack is designed to grow. To add any MCP server:

> **Naming convention:** name your service `-mcp` and use `//*` as its Caddy route prefix.
> The shared root (``) ties the service name, the route, and the public URL together.
> e.g. `my-tool-mcp` → `/my-tool/*` → `https:///my-tool/mcp`

> **Port convention:** assign each new MCP server the next available internal port, starting from `9002`.
> `sandbox-mcp` uses `9002`, so the next server gets `9003`, then `9004`, and so on.
> Ports are internal only (`expose:`, not `ports:`) — they never conflict with anything on your host.

**1. Add the service in `docker-compose.yml`:**

```yaml
my-tool-mcp:
  image: ghcr.io/supercorp-ai/supergateway:latest
  command: >
    --stdio "npx @some-scope/my-tool-mcp"
    --outputTransport streamableHttp
    --streamableHttpPath /mcp
    --port 9003
    --bearerToken "${MCP_BEARER_TOKEN}"
  expose:
    - "9003"
  restart: unless-stopped
```

**2. Add the route in `Caddyfile`:**

```caddy
route /my-tool/* {
    uri strip_prefix /my-tool
    reverse_proxy my-tool-mcp:9003
}
```

**3. Restart:**

```bash
docker compose up -d
```

Your new MCP is now live at `https:///my-tool/mcp`. Nothing else changes.

## Setup

### 1. Configure environment

```bash
cp .env.example .env
# edit .env with your values
```

| Variable | Description |
|---|---|
| `MCP_BEARER_TOKEN` | Shared secret required by all MCP endpoints |
| `NGROK_AUTHTOKEN` | From https://dashboard.ngrok.com/get-started/your-authtoken |
| `NGROK_DOMAIN` | Your static ngrok domain, e.g. `worthy-gorgeous-guppy.ngrok-free.app` |
| `SANDBOX_MOUNT_PATH` | Host directory mounted into `/workspace` inside the sandbox container |
| `UID` / `GID` | **Linux only.** Your host user's IDs — run `id -u` and `id -g` to get them. Passed as build args so files the sandbox creates in `/workspace` are owned by you, not root. Mac and Windows users can leave these unset. |

**Getting your ngrok static domain:**
1. Log in to the [ngrok dashboard](https://dashboard.ngrok.com)
2. Go to **Domains** → **New Domain** — your free static domain is created instantly
3. Copy the full domain (e.g. `worthy-gorgeous-guppy.ngrok-free.app`) into `NGROK_DOMAIN`

### 2. Build and start

```bash
docker compose up -d --build
```

### 3. Inspect ngrok

```bash
open http://localhost:4040
```

Confirm the tunnel shows **online** and the URL matches your `NGROK_DOMAIN`.

## Endpoints

| MCP Server | Public URL |
|---|---|
| Sandbox | `https:///sandbox/mcp` |

All requests require: `Authorization: Bearer `

## Agent Config

```json
{
  "mcpServers": {
    "sandbox": {
      "url": "https:///sandbox/mcp",
      "headers": { "Authorization": "Bearer " }
    }
  }
}
```

## Useful Commands

```bash
# Build and start
docker compose up -d --build

# Stop
docker compose down

# Tail all logs
docker compose logs -f

# Restart a single service
docker compose restart sandbox-mcp

# Pull latest images and restart
docker compose pull && docker compose up -d --build
```

## Troubleshooting

**ngrok tunnel is offline**
- Check `NGROK_AUTHTOKEN` is correct and not expired
- Confirm `NGROK_DOMAIN` exactly matches the domain in your ngrok dashboard — including the full subdomain
- Run `docker compose logs ngrok` for the raw error

**Agent gets a 401 Unauthorized**
- The bearer token is enforced by `supergateway` inside each MCP container, not by Caddy or ngrok
- Verify the `Authorization: Bearer ` header in your agent config matches `MCP_BEARER_TOKEN` in `.env` exactly (no extra spaces or quotes)
- Run `docker compose logs sandbox-mcp` to see rejected requests

**`uvx` or `supergateway` not found inside the container**
- This usually means the image wasn't rebuilt after a Dockerfile change
- Run `docker compose build sandbox-mcp` then `docker compose up -d`

**Port 9876 already in use on the host**
- Another process is using port 9876. Either stop it, or change the host port mapping in `docker-compose.yml`:
  ```yaml
  ports:
    - "9877:9876"  # change the left side only
  ```

**Files created by the sandbox are owned by root on the host (Linux only)**
- Set `UID` and `GID` in your `.env` to match your host user (`id -u` and `id -g`)
- Rebuild: `docker compose build sandbox-mcp && docker compose up -d`

## Security Notes

- All endpoints are protected by a bearer token — use a strong, unique `MCP_BEARER_TOKEN`. The token is validated by `supergateway` on every request before any tool is invoked; neither Caddy nor ngrok perform token checks
- The sandbox agent can fully read, write, and execute within `/workspace` only
- Mount only what the agent needs — do not mount your home directory or sensitive paths
- Never commit `.env` to git
- Keep your ngrok domain private to limit who can reach your endpoints

## License

MIT License — see [LICENSE](./LICENSE) for full details.

Copyright (c) 2026 oxcodexo

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [oxcodexo](https://github.com/oxcodexo)
- **Source:** [oxcodexo/mcp-launch](https://github.com/oxcodexo/mcp-launch)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-oxcodexo-mcp-launch
- Seller: https://agentstack.voostack.com/s/oxcodexo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.