MCP Remote Server

🌐 Remote HTTP/REST API server for hosting multiple MCP (Model Context Protocol) services with authentication and centralized management.

🎯 What is this?

This server allows you to:

• Host multiple MCP servers from a single endpoint
• Access your MCPs remotely over HTTP/REST API
• Secure access with API key authentication
• Manage multiple MCPs through a single configuration file
• Deploy easily with Docker support

🐳 Quick Start with Docker (Recommended)

Using Pre-built Image

# Pull the latest image
docker pull git.customable.host/customable-mcp/mcp-remote-server:latest

# Create config files
mkdir -p config
curl -o config/servers.json https://git.customable.host/customable-mcp/mcp-remote-server/raw/branch/main/config/servers.example.json
curl -o .env https://git.customable.host/customable-mcp/mcp-remote-server/raw/branch/main/.env.example

# Edit configuration
nano .env
nano config/servers.json

# Run with Docker Compose
docker-compose up -d

🚀 Quick Start from Source

Prerequisites

• Node.js 18+ or Docker
• Your MCP servers built and ready (e.g., browser-automation, custom-template)

Installation

# Clone the repository
git clone https://git.customable.host/customable-mcp/mcp-remote-server.git
cd mcp-remote-server

# Install dependencies
npm install

# Create configuration
cp config/servers.example.json config/servers.json
cp .env.example .env

# Edit .env with your API key
nano .env

# Edit config/servers.json with your MCP servers
nano config/servers.json

# Build
npm run build

# Start the server
npm start

📁 Configuration

Environment Variables (.env)

PORT=3000                    # Server port
HOST=0.0.0.0                # Server host
API_KEY=your-secret-key     # API key for authentication (CHANGE THIS!)
CORS_ORIGIN=*               # CORS origin (* for all, or specific domain)
MCP_CONFIG_PATH=./config/servers.json  # Path to MCP servers config

MCP Servers Configuration (config/servers.json)

{
  "servers": {
    "browser-automation": {
      "name": "Browser Automation",
      "description": "Universal browser automation with Playwright",
      "command": "node",
      "args": ["/opt/mcps/mcp-frontend-testing/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      },
      "enabled": true
    },
    "custom-server": {
      "name": "My Custom Server",
      "description": "My custom MCP server",
      "command": "node",
      "args": ["/path/to/your/mcp/server.js"],
      "env": {},
      "enabled": true
    }
  }
}

🔌 API Endpoints

All endpoints require the X-API-Key header with your configured API key.

Health Check (No auth required)

GET /health

List Available MCP Servers

GET /mcp/servers
Headers: X-API-Key: your-api-key

Response:

{
  "success": true,
  "servers": [
    {
      "id": "browser-automation",
      "name": "Browser Automation",
      "description": "Universal browser automation with Playwright",
      "status": "running",
      "capabilities": {
        "tools": true,
        "resources": true,
        "prompts": true
      }
    }
  ]
}

List Tools from a Specific Server

POST /mcp/{serverId}/tools/list
Headers: X-API-Key: your-api-key

Call a Tool

POST /mcp/{serverId}/tools/call
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "name": "calculator",
  "arguments": {
    "operation": "add",
    "a": 5,
    "b": 3
  }
}

List Resources

POST /mcp/{serverId}/resources/list
Headers: X-API-Key: your-api-key

Read a Resource

POST /mcp/{serverId}/resources/read
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "uri": "example://data"
}

List Prompts

POST /mcp/{serverId}/prompts/list
Headers: X-API-Key: your-api-key

Get a Prompt

POST /mcp/{serverId}/prompts/get
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "name": "example_prompt",
  "arguments": {
    "topic": "AI",
    "style": "formal"
  }
}

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Create config files
cp config/servers.example.json config/servers.json
cp .env.example .env

# Edit configuration
nano .env
nano config/servers.json

# Start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Using Docker Directly

# Build image
docker build -t mcp-remote-server .

# Run container
docker run -d \
  --name mcp-remote-server \
  -p 3000:3000 \
  -e API_KEY=your-secure-api-key \
  -v $(pwd)/config:/app/config:ro \
  mcp-remote-server

# View logs
docker logs -f mcp-remote-server

# Stop container
docker stop mcp-remote-server
docker rm mcp-remote-server

🔒 Security Best Practices

1. Change the default API key in .env
2. Use HTTPS in production (reverse proxy with nginx/caddy)
3. Restrict CORS origins to your domain
4. Keep API keys secret - never commit them to git
5. Use environment variables for sensitive data
6. Run as non-root user (Docker image uses node user)
7. Enable rate limiting (add a reverse proxy)

📊 Production Deployment

With Nginx Reverse Proxy

server {
    listen 80;
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }
}

With Systemd Service

Create /etc/systemd/system/mcp-remote-server.service:

[Unit]
Description=MCP Remote Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-remote-server
Environment="NODE_ENV=production"
ExecStart=/usr/bin/node dist/index.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable mcp-remote-server
sudo systemctl start mcp-remote-server
sudo systemctl status mcp-remote-server

🧪 Testing

Using curl

# Health check
curl http://localhost:3000/health

# List servers
curl -H "X-API-Key: your-api-key" \
  http://localhost:3000/mcp/servers

# List tools
curl -X POST \
  -H "X-API-Key: your-api-key" \
  http://localhost:3000/mcp/browser-automation/tools/list

# Call a tool
curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name":"calculator","arguments":{"operation":"add","a":5,"b":3}}' \
  http://localhost:3000/mcp/custom-template/tools/call

📚 Use Cases

1. Centralized MCP Management

   • Host all your MCPs from one server
   • Manage multiple MCPs through a single API

2. Remote Access

   • Access your MCPs from anywhere
   • No need for local MCP server installations

3. Team Collaboration

   • Share MCP servers with your team
   • Centralized authentication

4. Cloud Deployment

   • Deploy to cloud providers (AWS, GCP, Azure)
   • Scale horizontally

🛠️ Development

# Install dependencies
npm install

# Run in development mode with auto-rebuild
npm run dev

# Type check
npm run typecheck

# Clean build
npm run clean

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

📄 License

MIT License - See LICENSE file

🔄 CI/CD & Docker Registry

Pre-built Docker Images

Images are automatically built and published on every commit to main and for version tags.

Registry: git.customable.host/customable-mcp/mcp-remote-server

Available Tags:

• latest - Latest stable release from main branch
• develop - Development branch
• 1.0.0, 1.0, 1 - Semantic version tags
• main-abc1234 - Branch + commit SHA

Pull Images:

# Latest version
docker pull git.customable.host/customable-mcp/mcp-remote-server:latest

# Specific version
docker pull git.customable.host/customable-mcp/mcp-remote-server:1.0.0

# Development version
docker pull git.customable.host/customable-mcp/mcp-remote-server:develop

Platforms:

• linux/amd64 (x86_64)
• linux/arm64 (ARM64, Apple Silicon)

See CI-CD.md for complete CI/CD documentation.

🔗 Related Projects

• MCP Server Template
• Browser Automation MCP
• MCP Documentation

🆘 Troubleshooting

Server won't start?

• Check if port 3000 is available
• Verify config/servers.json paths are correct
• Ensure MCP servers are built

Authentication errors?

• Check X-API-Key header is set
• Verify API_KEY in .env matches

MCP server not responding?

• Check server paths in config/servers.json
• Verify MCP servers are built and executable
• Check logs: docker-compose logs -f

Need help? Open an issue: https://git.customable.host/customable-mcp/mcp-remote-server/issues