Installation Guide¶

Complete installation instructions for the MCP Gateway & Registry on various platforms.

Prerequisites¶

Node.js 16+: Required for building the React frontend
Container Runtime: Choose one:
Docker & Docker Compose: Standard container runtime
Podman & Podman Compose: Rootless alternative (recommended for macOS)
Authentication Provider: Choose one of the following:
Keycloak: Open-source identity management (see Keycloak Integration)
Amazon Cognito: AWS managed authentication (see Cognito Setup Guide)
Microsoft Entra ID: Azure Active Directory (see Entra ID Setup Guide)
SSL Certificate: Optional for HTTPS deployment in production

Quick Start (5 Minutes)¶

Docker Installation (Default)¶

# 1. Clone and setup
git clone https://github.com/agentic-community/mcp-gateway-registry.git
cd mcp-gateway-registry

# 2. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 3. Generate authentication credentials
./credentials-provider/generate_creds.sh

# 4. Install prerequisites
curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt-get update && sudo apt-get install -y docker.io docker-compose

# 5. Deploy
./build_and_run.sh --prebuilt

# 6. Access registry
open http://localhost:7860

Podman Installation (Rootless Alternative)¶

Recommended for macOS and rootless Linux environments

# 1. Clone and setup
git clone https://github.com/agentic-community/mcp-gateway-registry.git
cd mcp-gateway-registry

# 2. Install Podman (macOS)
brew install podman-desktop
# OR download from: https://podman-desktop.io/

# 3. Initialize Podman machine (macOS)
podman machine init
podman machine start

# 4. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 5. Deploy with Podman
./build_and_run.sh --prebuilt --podman

# 6. Access registry (note the different port for Podman)
open http://localhost:8080

Podman Port Mapping: - Main interface: http://localhost:8080 (HTTP) or https://localhost:8443 (HTTPS) - Registry API: http://localhost:7860 (unchanged) - All other internal services: unchanged ports

Installation on Amazon EC2¶

System Requirements¶

Minimum (Development): - EC2 Instance: t3.large (2 vCPU, 8GB RAM) - Storage: 20GB SSD - Network: Ports 80, 443, 7860, 8080 accessible

Recommended (Production): - EC2 Instance: t3.2xlarge (8 vCPU, 32GB RAM) - Storage: 50GB+ SSD - Network: Multi-AZ with load balancer

Detailed Setup Steps¶

Create Local Directories

mkdir -p ${HOME}/mcp-gateway/{servers,auth_server,secrets,logs}
cp -r registry/servers ${HOME}/mcp-gateway/
cp auth_server/scopes.yml ${HOME}/mcp-gateway/auth_server/

Configure Environment Variables

cp .env.example .env
nano .env  # Configure required values

Required Configuration: - ADMIN_PASSWORD: Secure admin password - COGNITO_USER_POOL_ID: Amazon Cognito User Pool ID - COGNITO_CLIENT_ID: Cognito App Client ID - COGNITO_CLIENT_SECRET: Cognito App Client Secret - AWS_REGION: AWS region for Cognito

Generate Authentication Credentials

# Configure OAuth credentials
cp credentials-provider/oauth/.env.example credentials-provider/oauth/.env
nano credentials-provider/oauth/.env

# Generate tokens and client configurations
./credentials-provider/generate_creds.sh

Install Dependencies

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv venv --python 3.12 && source .venv/bin/activate

# Install Docker
sudo apt-get update
sudo apt-get install --reinstall docker.io -y
sudo apt-get install -y docker-compose
sudo usermod -a -G docker $USER
newgrp docker

Deploy Services
```
./build_and_run.sh
```

Podman Installation (Rootless Containers)¶

Podman is a daemonless container engine that provides rootless container execution, making it ideal for macOS and environments where Docker requires privileged access.

Benefits of Podman¶

✅ Rootless Execution: No sudo or privileged ports required
✅ macOS Native: Works seamlessly with Podman Desktop on macOS
✅ Security: Enhanced container isolation without root privileges
✅ Compatibility: Drop-in replacement for Docker with similar CLI commands

Installation on macOS¶

Option 1: Podman Desktop (Recommended)

# Install via Homebrew
brew install podman-desktop

# Or download directly from:
# https://podman-desktop.io/

Option 2: Podman CLI Only

# Install Podman
brew install podman

# Initialize Podman machine
podman machine init --cpus 4 --memory 8192 --disk-size 50
podman machine start

# Verify installation
podman --version
podman compose version

Installation on Linux¶

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y podman podman-compose

# Fedora/RHEL
sudo dnf install -y podman podman-compose

# Arch Linux
sudo pacman -S podman podman-compose

# Verify installation
podman --version
podman compose version

Deploying with Podman¶

# Navigate to repository
cd mcp-gateway-registry

# Configure environment
cp .env.example .env
nano .env  # Configure required values

# Deploy with Podman (explicit)
./build_and_run.sh --prebuilt --podman

# Or let the script auto-detect (will use Podman if Docker not available)
./build_and_run.sh --prebuilt

Accessing Services with Podman¶

Important Port Differences:

Podman uses non-privileged host ports to avoid requiring root access:

Service	Docker Port	Podman Port	Description
Main UI (HTTP)	`http://localhost`	`http://localhost:8080`	Web interface
Main UI (HTTPS)	`https://localhost`	`https://localhost:8443`	Secure web interface
Registry API	`http://localhost:7860`	`http://localhost:7860`	API endpoint (unchanged)
Auth Server	`http://localhost:8888`	`http://localhost:8888`	Auth service (unchanged)
Keycloak	`http://localhost:8080`	`http://localhost:18080`	IdP (Podman uses 18080 because 8080 is used by the Registry UI)
Prometheus	`http://localhost:9090`	`http://localhost:9090`	Metrics (unchanged)
Grafana	`http://localhost:3000`	`http://localhost:3000`	Dashboards (unchanged)

Access the registry:

# With Podman
open http://localhost:8080

# With Docker
open http://localhost

Podman-Specific Configuration¶

The deployment uses docker-compose.podman.yml when using Podman, which:

Remaps privileged ports: Maps container ports 80→8080 and 443→8443 on the host
Adds SELinux labels: Adds :z mount options for SELinux compatibility (Linux)
Maintains compatibility: All internal service-to-service communication unchanged

Troubleshooting Podman¶

Issue: Permission denied on volume mounts

# Ensure directories exist with proper permissions
mkdir -p ${HOME}/mcp-gateway/{servers,agents,models,logs,security_scans,auth_server,ssl}
chmod -R 755 ${HOME}/mcp-gateway

Issue: Podman machine not starting (macOS)

# Reset Podman machine
podman machine stop
podman machine rm
podman machine init --cpus 4 --memory 8192 --disk-size 50
podman machine start

Issue: Port conflicts

# Check what's using ports 8080 or 8443
lsof -i :8080
lsof -i :8443

# Stop conflicting services or use different ports by editing docker-compose.podman.yml

Issue: Podman compose command not found

# Install podman-compose separately
pip install podman-compose

# Or use podman-compose wrapper
brew install podman-compose

HTTPS Configuration¶

By default, MCP Gateway runs on HTTP (port 80). To enable HTTPS for production deployments:

1. Obtain SSL Certificates¶

Option A: Let's Encrypt (Recommended)

# Install certbot
sudo apt-get update
sudo apt-get install -y certbot

# Get certificate (requires domain and port 80 accessible)
sudo certbot certonly --standalone -d your-domain.com

Option B: Commercial CA Purchase SSL certificate from a trusted Certificate Authority.

2. Copy Certificates to Expected Location¶

MCP Gateway expects SSL certificates at ${HOME}/mcp-gateway/ssl/. The build_and_run.sh script will automatically set up the proper directory structure.

# Create the ssl directory structure
mkdir -p ${HOME}/mcp-gateway/ssl/certs
mkdir -p ${HOME}/mcp-gateway/ssl/private

# Copy your certificates to the expected location
# Replace paths below with your actual certificate locations
cp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem
cp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem

# Set proper permissions
chmod 644 ${HOME}/mcp-gateway/ssl/certs/fullchain.pem
chmod 600 ${HOME}/mcp-gateway/ssl/private/privkey.pem

Note: If SSL certificates are not present at ${HOME}/mcp-gateway/ssl/certs/fullchain.pem and ${HOME}/mcp-gateway/ssl/private/privkey.pem, the MCP Gateway will automatically run in HTTP-only mode.

3. Configure Security Group¶

Enable TCP port 443 for HTTPS access
Restrict access to authorized IP ranges
Keep port 80 open for HTTP and Let's Encrypt renewals

4. Deploy and Verify¶

# Start/restart the services
./build_and_run.sh

# Check logs for SSL certificate detection
docker compose logs registry | grep -i ssl

# Expected output:
# "SSL certificates found - HTTPS enabled"
# "HTTPS server will be available on port 443"

# Test HTTPS access
curl https://your-domain.com

Certificate Renewal (Let's Encrypt)¶

Let's Encrypt certificates expire after 90 days. Set up automatic renewal:

# Add to crontab
sudo crontab -e

# Add this line (checks twice daily, renews if needed)
0 0,12 * * * certbot renew --quiet && cp /etc/letsencrypt/live/your-domain/fullchain.pem ${HOME}/mcp-gateway/ssl/certs/fullchain.pem && cp /etc/letsencrypt/live/your-domain/privkey.pem ${HOME}/mcp-gateway/ssl/private/privkey.pem && docker compose restart registry

Troubleshooting¶

HTTPS not working? - Check certificate files exist: ls -la ${HOME}/mcp-gateway/ssl/certs/ ${HOME}/mcp-gateway/ssl/private/ - Verify certificates are present: ${HOME}/mcp-gateway/ssl/certs/fullchain.pem and ${HOME}/mcp-gateway/ssl/private/privkey.pem - Check container logs: docker compose logs registry | grep -i ssl - Verify port 443 is accessible: sudo netstat -tlnp | grep 443 - Ensure certificates are from a trusted CA

Installation on Amazon EKS¶

For production Kubernetes deployments, see the EKS deployment guide.

Architecture Overview¶

graph TB
    subgraph "EKS Cluster"
        subgraph "Ingress"
            ALB[Application Load Balancer]
            IC[Ingress Controller]
        end

        subgraph "Application Pods"
            RP[Registry Pod]
            AS[Auth Server Pod]
            NG[Nginx Pod]
        end

        subgraph "MCP Servers"
            MS1[MCP Server 1]
            MS2[MCP Server 2]
            MSN[MCP Server N]
        end
    end

    subgraph "AWS Services"
        COG[Amazon Cognito]
        CW[CloudWatch]
        ECR[Amazon ECR]
    end

    ALB --> IC
    IC --> RP
    IC --> AS
    IC --> NG
    NG --> MS1
    NG --> MS2
    NG --> MSN
    AS --> COG
    RP --> CW

Key Benefits of EKS Deployment¶

High Availability: Multi-AZ pod distribution
Auto Scaling: Horizontal pod autoscaling based on metrics
Service Mesh: Istio integration for advanced traffic management
Observability: Native integration with CloudWatch and Prometheus
Security: Pod security policies and network policies

Post-Installation¶

Verify Installation¶

Check Service Status

docker-compose ps
docker-compose logs -f

Test Web Interface
Navigate to http://localhost:7860
Login with admin credentials
Verify MCP server health status
Test Authentication
```
cd tests
./mcp_cmds.sh ping
```

Configure AI Coding Assistants¶

Generate Client Configurations

./credentials-provider/generate_creds.sh
ls .oauth-tokens/  # View generated configurations

Setup VS Code

cp .oauth-tokens/vscode-mcp.json ~/.vscode/settings.json

Setup Roo Code

cp .oauth-tokens/mcp.json ~/.vscode/mcp-settings.json

For detailed AI assistant setup, see AI Coding Assistants Setup Guide.

Troubleshooting¶

Common Issues¶

Services won't start:

# Check Docker daemon
sudo systemctl status docker

# Check environment variables
cat .env | grep -v SECRET

# View detailed logs
docker-compose logs --tail=50

Authentication failures:

# Verify Cognito configuration
aws cognito-idp describe-user-pool --user-pool-id YOUR_POOL_ID

# Test credential generation
cd credentials-provider && ./generate_creds.sh --verbose

Network connectivity issues:

# Check port availability
sudo netstat -tlnp | grep -E ':(80|443|7860|8080)'

# Test internal services
curl -v http://localhost:7860/health

For more troubleshooting help, see Troubleshooting Guide.

Next Steps¶

Authentication Setup - Configure identity providers
AI Assistant Integration - Setup development tools
Production Deployment - High availability configuration
API Reference - Programmatic management