Runner
Runs and manages MCP servers
Installation
npx mcp-runnerAsk AI about Runner
Powered by Claude · Grounded in docs
I know everything about Runner. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
A secure, isolated platform for running MCP (Model Context Protocol) servers in Docker containers with GVisor runtime. Built with NestJS and TypeScript, this service provides ephemeral, multi-tenant deployments of MCP servers with robust security isolation.
Motivation
This project solves key challenges when integrating with MCP servers:
- Security: Run untrusted MCP servers in isolated containers that cannot access host resources or communicate with each other
- Multi-tenancy: Multiple clients can safely connect to the same MCP server instance or you can set up multiple isolated instances for different users
- Ephemeral deployments: Complete cleanup of all deployment data (configs, logs, network, users) when deleted
- Legacy transport support: Connect to local MCP servers and expose them via Streamable HTTP or SSE endpoints
- Resource management: Enforce memory and CPU limits on shared infrastructure
Perfect for developers building applications that need to integrate with various MCP servers, especially untrusted or locally-running ones like Wikipedia MCP.
License
Copyright (C) 2025 Tangier AI, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
How It Works
The secure MCP runner operates through several layers of isolation:
- Container Isolation: Each MCP server runs in its own Docker container with GVisor runtime (
runsc) - Network Isolation: Containers are placed in isolated bridge networks that prevent inter-container communication
- User Isolation: Each container runs as a unique unprivileged Linux user with minimal permissions
- Resource Limits: Memory and CPU constraints prevent resource exhaustion
- Transport Standardization: All MCP servers are exposed via Streamable HTTP/SSE endpoints for remote access regardless of their original transport (includes STDIO)
Security Model
Security is enforced through multiple layers:
- GVisor Runtime: All containers use
runscruntime for kernel-level isolation - Capability Dropping: Containers drop dangerous capabilities (
SYS_ADMIN,NET_ADMIN,SYS_PTRACE,SYS_MODULE) - Security Options:
no-new-privileges,apparmor:docker-default,seccomp:unconfined - Network Isolation: Networks are created for each deployment with inter-container communication disabled
- DNS Control: Containers use only Google (8.8.8.8) and Cloudflare (1.1.1.1) DNS servers
- Ephemeral Data: Complete cleanup of all deployment artifacts (containers, networks, users, logs) upon deletion
Quick Start
Server Setup
Create a new Ubuntu 24.04 VM (minimum 2GB RAM recommended) and run:
# Download and run the setup script
wget https://raw.githubusercontent.com/tangier-ai/mcp-runner/refs/heads/main/setup.sh
sudo bash setup.sh
Or using curl:
# Download and run the setup script
curl -O https://raw.githubusercontent.com/tangier-ai/mcp-runner/refs/heads/main/setup.sh
sudo bash setup.sh
This setup script is the setup.sh file in this repository.
Running the Service
Start the MCP runner service:
docker run -d \
--privileged \
--network=host \
--name mcp-runner-container \
--restart=always \
-e NODE_ENV=production \
-e API_KEY=your-secure-api-key \
-e BIND_IP=0.0.0.0 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /etc:/etc \
-v /var/mcp-runner:/var/mcp-runner \
tangierai/mcp-runner:latest
The service will start on localhost:3000 by default.
Docker Arguments Explained
--privileged: Required for the service to create users and perform Docker in Docker operations--network=host: Uses the host network stack so the mcp-runner can appropriately forward requests to the ip addresses of the containers--restart=always: Automatically restarts the container if it stops or on system reboot-v /var/run/docker.sock:/var/run/docker.sock: Mounts the Docker socket to allow container management-v /etc:/etc: Mounts system configuration for user management, mounting /etc/passwd is insufficient-v /var/mcp-runner:/var/mcp-runner: Persistent storage for the application database
Environment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
PORT | Server port | 3000 | No |
BIND_IP | Interface to bind to (use 0.0.0.0 for public access) | 127.0.0.1 | No |
API_KEY | Authentication key | Auto-generated | No |
SENTRY_DSN | Sentry error reporting endpoint | - | No |
NODE_ENV | Environment mode (production/development) | - | No |
If no API_KEY is provided, one will be auto-generated and logged to the console.
External Access
By default, the service binds to localhost only. For external access:
Option 1: Direct binding
docker run -d \
--privileged \
--network=host \
--name mcp-runner-container \
--restart=always \
-e NODE_ENV=production \
-e API_KEY=your-secure-api-key \
-e BIND_IP=0.0.0.0 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /etc:/etc \
-v /var/mcp-runner:/var/mcp-runner \
tangierai/mcp-runner:latest
Option 2: Nginx proxy
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
client_max_body_size 0;
proxy_http_version 1.1;
proxy_request_buffering off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
API Usage
Authentication
All API requests require an X-API-Key header:
curl -H "X-API-Key: your-api-key" http://localhost:3000/api/deployment
Create a Deployment
curl -X POST http://localhost:3000/api/deployment \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"image": "mcp/sequentialthinking:latest",
"transport": {
"type": "stdio"
},
"maxMemory": 512,
"maxCpus": 1,
"deleteAfterSeconds": 3600
}'
List Deployments
curl -H "X-API-Key: your-api-key" http://localhost:3000/api/deployment
Connect to MCP Server
Once deployed, connect to your MCP server via the provided SSE or HTTP endpoints.
Monitoring & Observability
Sentry Integration
Enable error reporting with Sentry, include a SENTRY_DSN environment variable when starting the service:
docker run -d \
--privileged \
--network=host \
--name mcp-runner-container \
--restart=always \
-e NODE_ENV=production \
-e SENTRY_DSN=your-sentry-dsn \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /etc:/etc \
-v /var/mcp-runner:/var/mcp-runner \
tangierai/mcp-runner:latest
Privacy: Environment variables and arguments from deployment requests are automatically stripped from Sentry error reports to prevent data leakage.
Source Maps
To publish source maps to Sentry for better error tracking:
docker run -d \
-e SENTRY_ORG=your-org \
-e SENTRY_PROJECT=your-project \
-e SENTRY_AUTH_TOKEN=your-auth-token \
tangierai/mcp-runner:latest \
publish:sourcemap
Development
Local Development
Install dependencies:
npm install
Start development server:
npm run start:dev
Building
Build and run locally:
npm run build
npm run start:prod
API Documentation
Once running, visit http://localhost:3000/api for interactive Swagger documentation.
