Complete macOS Setup Guide: MCP Gateway & Registry¶

This guide provides a comprehensive, step-by-step walkthrough for setting up the MCP Gateway & Registry on macOS. Perfect for local development and testing.

Table of Contents¶

Prerequisites
Container Runtime Choice
Cloning and Initial Setup
Environment Configuration
Starting Keycloak Services
Keycloak Configuration
Create Test Agent
Starting All Services
Verification and Testing
Podman Deployment
Troubleshooting

1. Prerequisites¶

System Requirements¶

macOS: 12.0 (Monterey) or later
RAM: At least 8GB (16GB recommended)
Storage: At least 10GB free space
Administrator Access: Sudo privileges required for Docker volume setup

Required Software¶

Container Runtime (choose one): - Docker Desktop: Install from https://www.docker.com/products/docker-desktop/ - Includes Docker Compose - Requires privileged port access - Important: Make sure Docker Desktop is running before proceeding! - Podman Desktop (Alternative, recommended for rootless): Install from https://podman-desktop.io/ or via Homebrew - Rootless container execution - No privileged port requirements - See Podman Deployment section below

Other Requirements: - Node.js: Version 20.x LTS - Install from https://nodejs.org/ or via Homebrew (not needed with --prebuilt flag) - Python: Version 3.12+ - Install via Homebrew (brew install python@3.12) - UV Package Manager: Install with curl -LsSf https://astral.sh/uv/install.sh | sh - Git: Usually pre-installed on macOS - jq: Install via Homebrew (brew install jq)

2. Container Runtime Choice¶

Choose between Docker and Podman based on your needs:

Docker (Default)¶

✅ Best for: Standard deployment, familiar workflow
✅ Uses privileged ports (80, 443)
✅ Access at http://localhost
⚠️ Requires Docker daemon running

Podman (Rootless Alternative)¶

✅ Best for: Rootless deployment, no Docker daemon
✅ Uses non-privileged ports (8080, 8443)
✅ Access at http://localhost:8080
✅ More secure, no root access needed

This guide uses Docker by default. For Podman-specific instructions, see Section 10: Podman Deployment.

3. Cloning and Initial Setup¶

Clone the Repository¶

# Create workspace directory
mkdir -p ~/workspace
cd ~/workspace

# Clone the repository
git clone https://github.com/agentic-community/mcp-gateway-registry.git
cd mcp-gateway-registry

# Verify you're in the right directory
ls -la
# Should see: docker-compose.yml, .env.example, README.md, etc.

Setup Python Virtual Environment¶

# Create and activate Python virtual environment
uv sync
source .venv/bin/activate

# Verify virtual environment is active
which python
# Should show: /Users/[username]/workspace/mcp-gateway-registry/.venv/bin/python

4. Environment Configuration¶

Create Environment File¶

# Copy the example environment file
cp .env.example .env

# Generate a secure SECRET_KEY
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(64))")
echo "Generated SECRET_KEY: $SECRET_KEY"

# Open .env file for editing
nano .env

Configure Essential Settings¶

In the .env file, make these changes:

# Set authentication provider to Keycloak
AUTH_PROVIDER=keycloak

# Set auth server URL for local development
# This URL must be accessible from your browser for OAuth redirects
AUTH_SERVER_EXTERNAL_URL=http://localhost

# Set secure passwords (CHANGE THESE!)
KEYCLOAK_ADMIN_PASSWORD=your_secure_admin_password_here
KEYCLOAK_DB_PASSWORD=your_secure_db_password_here

# Set your generated SECRET_KEY
SECRET_KEY=[paste-your-generated-key-here]


# Leave other Keycloak settings as default for now
KEYCLOAK_REALM=mcp-gateway
KEYCLOAK_CLIENT_ID=mcp-gateway-web
# Note: CLIENT_SECRET will be updated later after Keycloak initialization

Important: Choose strong, unique passwords and remember them - you'll need the admin password for Keycloak login!

Download Required Embeddings Model¶

The MCP Gateway requires a sentence-transformers model for intelligent tool discovery. Download it to the shared models directory:

# Download the embeddings model (this may take a few minutes)
huggingface-cli download sentence-transformers/all-MiniLM-L6-v2 --local-dir ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2

# Verify the model was downloaded
ls -la ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2/
# You should see model files like model.safetensors, config.json, etc.

Note: This command automatically creates the necessary directory structure and downloads all required model files (~90MB). If you don't have hf command installed, install it first with pip install huggingface_hub[cli].

5. Starting Keycloak Services¶

Set Keycloak Passwords¶

Important: These environment variables will override the values in your .env file. Use the SAME passwords you configured in Step 4!

# Use the SAME passwords you set in the .env file in Step 4!
# Replace these with your actual passwords from Step 4
# Note: Use single quotes to prevent issues with special characters
export KEYCLOAK_ADMIN_PASSWORD='your-admin-password-here-from-env'
export KEYCLOAK_DB_PASSWORD='your-db-password-here-from-env'

# Verify they're set correctly
echo "Admin Password: $KEYCLOAK_ADMIN_PASSWORD"
echo "DB Password: $KEYCLOAK_DB_PASSWORD"

Critical: These passwords MUST match what you set in the .env file in Step 4. If they don't match, Keycloak initialization will fail!

Start Database and Keycloak¶

With Docker:

# Start only the database and Keycloak services first
docker compose up -d keycloak-db keycloak

# Check if services are starting
docker-compose ps

# Monitor Keycloak logs until ready
docker-compose logs -f keycloak
# Wait for: "Keycloak 25.x.x started in xxxms"
# Press Ctrl+C when you see this message

Wait Time: Allow 2-3 minutes for Keycloak to fully initialize.

Verify Keycloak is Running¶

# Test basic connectivity
curl -s http://localhost:8080/realms/master | jq '.realm'
# Should return: "master"

# Check health status
docker-compose ps keycloak
# Should show "Up" status (may show "unhealthy" - this is normal for dev mode)

Fix macOS SSL Requirement (Critical Step)¶

Why this is needed on macOS: Docker on macOS runs in a virtualized environment, which causes Keycloak to treat localhost requests as external network traffic. This triggers Keycloak's default security policy requiring HTTPS for external connections.

# Configure Keycloak admin CLI (use your actual admin password)
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password "${KEYCLOAK_ADMIN_PASSWORD}"

# Disable SSL requirement for master realm
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

# Verify the fix worked
curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/admin/"
# Should return: 302 (redirect to login - this is correct)

Important: This step MUST be completed before running the init-keycloak.sh script, or the initialization will fail.

5. Keycloak Configuration¶

Initialize Keycloak Configuration¶

Important: This is a two-step process. The initialization script creates the realm and clients but does NOT save the credentials to files.

# Make the setup script executable
chmod +x keycloak/setup/init-keycloak.sh

# Step 1: Run the Keycloak initialization
./keycloak/setup/init-keycloak.sh

# Expected output:
# ✓ Waiting for Keycloak to be ready...
# ✓ Keycloak is ready!
# ✓ Logged in to Keycloak
# ✓ Created realm: mcp-gateway
# ✓ Created clients: mcp-gateway-web and mcp-gateway-m2m
# ... more success messages ...
# ✓ Client secrets generated!
#
# IMPORTANT: The script will tell you to run get-all-client-credentials.sh
# to retrieve and save the credentials. This is the next required step!

# Step 2: Retrieve and save all client credentials (REQUIRED)
chmod +x keycloak/setup/get-all-client-credentials.sh
./keycloak/setup/get-all-client-credentials.sh

# This will:
# - Connect to Keycloak and retrieve all client secrets
# - Save credentials to .oauth-tokens/keycloak-client-secrets.txt
# - Create individual JSON files: .oauth-tokens/<client-id>.json
# - Create individual env files: .oauth-tokens/<client-id>.env
# - Display a summary of all saved credentials

# Expected output:
# ✓ Admin token obtained
# ✓ Found and saved: mcp-gateway-web
# ✓ Found and saved: mcp-gateway-m2m
# Files created in: .oauth-tokens/

Fix SSL Requirement for mcp-gateway Realm¶

Important: Now that the mcp-gateway realm is created, we need to disable SSL for it as well:

# Configure Keycloak admin CLI (if session expired)
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password "${KEYCLOAK_ADMIN_PASSWORD}"

# Disable SSL requirement for the mcp-gateway realm
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/mcp-gateway -s sslRequired=NONE

# Verify both realms are accessible
curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/admin/"
# Should return: 302

curl -s http://localhost:8080/realms/mcp-gateway | jq '.realm'
# Should return: "mcp-gateway"

Retrieve Client Credentials¶

# Make the credentials script executable
chmod +x keycloak/setup/get-all-client-credentials.sh

# Retrieve all client credentials
./keycloak/setup/get-all-client-credentials.sh

Expected Output:

Admin token obtained
Found and saved: mcp-gateway-web (Secret: JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv)
Found and saved: mcp-gateway-m2m (Secret: iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo)
Files created in: .oauth-tokens/

Update Environment with Client Secrets¶

# View the retrieved client secrets
cat .oauth-tokens/keycloak-client-secrets.txt

# Copy the secrets and update your .env file
nano .env

# Update these lines with the actual secret values:
# KEYCLOAK_CLIENT_SECRET=[paste-web-client-secret-here]
# KEYCLOAK_M2M_CLIENT_SECRET=[paste-m2m-client-secret-here]

# Save and exit (Ctrl+X, then Y, then Enter)

6. Create Your First AI Agent Account¶

# Make the agent setup script executable
chmod +x keycloak/setup/setup-agent-service-account.sh

# Create a test agent with full access
./keycloak/setup/setup-agent-service-account.sh \
  --agent-id test-agent \
  --group mcp-servers-unrestricted

# Create an agent for AI coding assistants (VS Code, cursor, etc.)
./keycloak/setup/setup-agent-service-account.sh \
  --agent-id ai-coding-assistant \
  --group mcp-servers-unrestricted

# Create an agent with restricted access for registry operations
./keycloak/setup/setup-agent-service-account.sh \
  --agent-id registry-operator \
  --group mcp-servers-restricted

# Note: The script does not display the credentials at the end.
# Your Client ID is: agent-test-agent-m2m

# Retrieve and save ALL client credentials (recommended):
./keycloak/setup/get-all-client-credentials.sh

# This will:
# - Retrieve credentials for ALL clients in the realm
# - Save all credentials to .oauth-tokens/keycloak-client-secrets.txt
# - Create individual JSON files: .oauth-tokens/<client-id>.json
# - Create individual env files: .oauth-tokens/<client-id>.env
# - Display a summary of all credentials saved

# Or to get just one specific client:
./keycloak/setup/get-agent-credentials.sh agent-test-agent-m2m

Important: Save the Client ID and Client Secret shown in the output. You'll need these to authenticate your AI agents.

Update .env File with Client Secrets¶

Critical Step: After running get-all-client-credentials.sh, you MUST update your .env file with the retrieved client secrets:

# View the retrieved client secrets
cat .oauth-tokens/keycloak-client-secrets.txt

# You'll see output like:
# KEYCLOAK_CLIENT_ID=mcp-gateway-web
# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv
#
# KEYCLOAK_M2M_CLIENT_ID=mcp-gateway-m2m
# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo

# Update your .env file with these exact secret values
nano .env

# Find and update these lines with the actual secret values from above:
# KEYCLOAK_CLIENT_SECRET=JyJzW00JeUBaCmH9Z5xtYDhE2MsGqOSv
# KEYCLOAK_M2M_CLIENT_SECRET=iCjPsMLLmet124K8b7FCfcEcRJ9bx4Oo

# Save and exit (Ctrl+X, then Y, then Enter)

Note: These secrets are auto-generated by Keycloak and are different each time you run init-keycloak.sh. Always use the latest values from .oauth-tokens/keycloak-client-secrets.txt.

Generate Access Tokens for All Keycloak Users and Agents¶

Generate access tokens for all configured agents and users:

# Generate access tokens for all agents
./credentials-provider/keycloak/generate_tokens.py --all-agents

This will create access token files (both .json and .env formats) for all Keycloak service accounts in the .oauth-tokens/ directory.

Note: If you want tokens to last longer than the default 5 minutes, see Configure Token Lifetime before generating tokens.

Verify Keycloak is Running¶

Open a web browser and navigate to:

http://localhost:8080

You should see the Keycloak login page. You can log in with: - Username: admin - Password: The password you set in KEYCLOAK_ADMIN_PASSWORD

7. Starting All Services¶

Start Services with Pre-built Images¶

Important macOS Docker Volume Sharing: On macOS, Docker Desktop only shares certain directories by default (like /Users, /tmp, /private). The /opt and /var/log directories we need are NOT shared by default, so we must create them with proper ownership for Docker containers to access them.

Note: If you encounter permission issues, you may need to add /opt to Docker Desktop's shared directories: 1. Open Docker Desktop 2. Go to Settings > Resources > Virtual file shares 3. Add /opt to the list of shared directories 4. Click "Apply & Restart"

# Create necessary directories
# Using ${HOME}/mcp-gateway to avoid needing sudo permissions
mkdir -p ${HOME}/mcp-gateway/{servers,models,auth_server,secrets/fininfo,logs,ssl}

# Make build script executable
chmod +x build_and_run.sh

# Start all services using pre-built images (faster, no build required)
./build_and_run.sh --prebuilt

# This will:
# - Use pre-built container images from Docker registry
# - Skip React frontend build (already included in images)
# - Create necessary directories
# - Start all services
# - Much faster than building locally!

Benefits of using --prebuilt: - Instant deployment: No build time required - No Node.js issues: Pre-built frontend already included - Consistent experience: Same tested images for all users - Bandwidth efficient: Optimized, compressed images

Verify All Services are Running¶

# Check all services status
docker-compose ps

# Expected services (all should show "Up"):
# - keycloak-db
# - keycloak
# - auth-server
# - registry
# - nginx (or similar proxy)
# - currenttime-server
# - fininfo-server
# - mcpgw-server
# - realserverfaketools-server

Monitor Service Logs¶

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f auth-server
docker-compose logs -f registry

# Press Ctrl+C to exit log viewing

8. Verification and Testing¶

Test Web Interface¶

Open your web browser and navigate to:
```
http://localhost
```
Login Page: You should see the MCP Gateway Registry login page
Login with Keycloak: Click "Login with Keycloak" and use:
Username: admin
Password: The password you set in KEYCLOAK_ADMIN_PASSWORD

Test API Access¶

# Test registry health
curl http://localhost/health
# Expected: {"status":"healthy","timestamp":"..."}

# Test Keycloak realm
curl http://localhost:8080/realms/mcp-gateway | jq '.realm'
# Expected: "mcp-gateway"

Test Python MCP Client¶

# Activate virtual environment
source .venv/bin/activate

# Load agent credentials
source .oauth-tokens/agent-test-agent-m2m.env

# Test connectivity
uv run cli/mcp_client.py ping

# Expected output:
# ✓ M2M authentication successful
# Session established: [session-id]
# {"jsonrpc": "2.0", "id": 2, "result": {}}

# List available tools
uv run cli/mcp_client.py list

# Test a simple tool
uv run cli/mcp_client.py --url http://localhost/currenttime/mcp call --tool current_time_by_timezone --args '{"tz_name":"America/New_York"}'

Test Admin Console¶

# Access Keycloak admin console
open http://localhost:18080/admin/

# Login with:
# Username: admin
# Password: The password you set in KEYCLOAK_ADMIN_PASSWORD

# You should see the Keycloak admin interface
# Navigate to: mcp-gateway realm > Clients
# Verify: mcp-gateway-web and mcp-gateway-m2m clients exist

10. Podman Deployment¶

This section provides complete instructions for deploying MCP Gateway & Registry using Podman instead of Docker on macOS. Podman offers rootless container execution without requiring privileged port access.

Why Podman?¶

✅ Rootless Execution: No sudo or root access required
✅ No Privileged Ports: Uses ports 8080/8443 instead of 80/443
✅ Enhanced Security: Better container isolation
✅ No Daemon: Unlike Docker, Podman doesn't require a background daemon
✅ Docker-Compatible: Similar CLI commands and Compose support

Installation¶

Option 1: Podman Desktop (Recommended)

# Install via Homebrew
brew install podman-desktop

# Launch Podman Desktop from Applications
# Or download from: https://podman-desktop.io/

Option 2: Podman CLI Only

# Install Podman
brew install podman

# Install additional tools
brew install podman-compose

Initialize Podman Machine¶

Podman on macOS runs containers in a lightweight Linux VM:

# Initialize Podman machine with adequate resources
podman machine init --cpus 4 --memory 8192 --disk-size 50

# Start the machine
podman machine start

# Verify installation
podman --version
podman compose version
podman machine list

Expected output:

NAME                     VM TYPE     CREATED      LAST UP            CPUS        MEMORY      DISK SIZE
podman-machine-default*  qemu        2 hours ago  Currently running  4           8GiB        50GiB

Complete Setup with Podman¶

Follow the same steps as the Docker guide (Sections 3-8), but use Podman commands:

1. Clone and Configure (same as Section 3-4)

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

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

2. Start Keycloak with Podman

# Set passwords (must match .env file)
export KEYCLOAK_ADMIN_PASSWORD='your-admin-password'
export KEYCLOAK_DB_PASSWORD='your-db-password'

# Start Keycloak services
podman compose up -d keycloak-db keycloak

# Wait for services (takes ~60 seconds)
podman compose ps

# Follow logs
podman compose logs -f keycloak

3. Configure Keycloak (same as Section 5-6)

# Disable SSL requirement
podman exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master \
  --user admin --password "${KEYCLOAK_ADMIN_PASSWORD}"

podman exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  update realms/master -s sslRequired=NONE

# Run Keycloak setup scripts
cd keycloak/setup
./create-realm-and-clients.sh
./get-all-client-credentials.sh

# Create test agent
./setup-agent-service-account.sh test-agent-1 registry-users-lob1
cd ../..

4. Deploy All Services with Podman

# Deploy using pre-built images (recommended for Intel Macs)
./build_and_run.sh --prebuilt --podman

# For Apple Silicon, build locally instead
./build_and_run.sh --podman

Apple Silicon Users: Don't use --prebuilt with Podman on ARM64. The pre-built images are amd64 and will cause errors. Use ./build_and_run.sh --podman to build natively. See Podman on Apple Silicon Guide.

The script automatically: - Detects Podman usage - Applies docker-compose.podman.yml overlay - Maps ports to non-privileged equivalents (8080/8443) - Configures volume mounts with proper SELinux labels

Access Services¶

Important: With Podman, services use different host ports:

Service	URL (Podman)
Main UI	`http://localhost:8080`
Main UI (HTTPS)	`https://localhost:8443`
Registry API	`http://localhost:7860`
Keycloak Admin	`http://localhost:18080/admin`
Auth Server	`http://localhost:8888`
Prometheus	`http://localhost:9090`
Grafana	`http://localhost:3000`

Open in browser:

# Main interface (note port 8080)
open http://localhost:8080

# Registry API (unchanged)
open http://localhost:7860

# Keycloak admin console
open http://localhost:18080/admin

Podman-Specific Commands¶

Container Management:

# List running containers
podman compose ps
# or: podman ps

# View logs
podman compose logs -f
podman compose logs -f registry
podman logs mcp-gateway-registry-registry-1

# Stop services
podman compose down

# Restart service
podman compose restart registry

# Execute commands in container
podman exec -it mcp-gateway-registry-registry-1 bash

Resource Management:

# View resource usage
podman stats

# Check Podman machine resources
podman machine inspect podman-machine-default

# Adjust machine resources (requires restart)
podman machine stop
podman machine rm
podman machine init --cpus 8 --memory 16384 --disk-size 100
podman machine start

Volume Management:

# List volumes
podman volume ls

# Inspect volume
podman volume inspect mcp-gateway-registry_metrics-db-data

# Remove unused volumes
podman volume prune

Testing with Podman¶

Update test scripts to use Podman ports:

# Test registry health
curl http://localhost:7860/health

# Test main interface (note port 8080)
curl http://localhost:8080/

# Test with MCP client
cd cli
python mcp_client.py \
  --url http://localhost/mcpgw/mcp \
  --token-file ../.oauth-tokens/agent-test-agent-1-m2m.env \
  --command ping

Troubleshooting Podman¶

Issue: Podman machine won't start

# Check status
podman machine list

# View machine logs
podman machine ssh systemctl status

# Reset machine
podman machine stop
podman machine rm
podman machine init --cpus 4 --memory 8192
podman machine start

Issue: Port 8080 already in use

# Check what's using the port
lsof -i :8080

# Option 1: Stop conflicting service
# Option 2: Edit docker-compose.podman.yml to use different ports
nano docker-compose.podman.yml
# Change "8080:80" to "8081:80"

Issue: Permission denied on volumes

# Ensure directories exist
mkdir -p ${HOME}/mcp-gateway/{servers,agents,models,logs}

# Check permissions
ls -la ${HOME}/mcp-gateway/

# Fix if needed
chmod -R 755 ${HOME}/mcp-gateway/

Issue: Containers fail to start

# Check logs
podman compose logs

# Verify machine has enough resources
podman machine inspect | grep -A5 "Resources"

# Increase if needed (see Resource Management above)

Issue: podman compose command not found

# Install podman-compose
pip install podman-compose

# Or install via Homebrew
brew install podman-compose

# Verify
podman compose version

Switching Between Docker and Podman¶

You can switch between Docker and Podman without changing configurations:

# Stop Docker services
docker compose down

# Start with Podman (Intel Mac)
./build_and_run.sh --prebuilt --podman

# Start with Podman (Apple Silicon - omit --prebuilt)
# ./build_and_run.sh --podman

# Or vice versa:
podman compose down
./build_and_run.sh --prebuilt

Apple Silicon Note: When switching to Podman on Apple Silicon, use ./build_and_run.sh --podman (without --prebuilt).

Note: Database volumes and configurations are separate between Docker and Podman. You'll need to reconfigure Keycloak when switching.

Performance Considerations¶

Podman Machine on macOS: - Runs in a QEMU VM (like Docker Desktop) - Performance similar to Docker Desktop - Recommended: 4+ CPUs, 8GB+ RAM - SSD recommended for disk operations

Tips for Better Performance: 1. Allocate sufficient resources to Podman machine 2. Use --prebuilt flag to avoid local builds 3. Keep Podman Desktop updated 4. Use SSD for Podman machine storage

11. Troubleshooting¶

Common macOS Issues¶

Docker/Podman Not Running¶

Docker:

# Check if Docker is running
docker ps

# If error, start Docker Desktop from Applications
# Wait for whale icon to appear in menu bar

Podman:

# Check if Podman machine is running
podman machine list

# If not running, start it
podman machine start

# Verify
podman ps

Port Conflicts¶

# Check what's using ports
lsof -i :80
lsof -i :8080
lsof -i :7860

# Kill conflicting processes if needed
sudo lsof -ti :80 | xargs kill

Permission Issues¶

# Fix Docker permissions
sudo chown -R $(whoami) ~/.docker

# Fix file permissions
chmod +x keycloak/setup/*.sh
chmod +x build_and_run.sh

# No additional ownership fixes needed - all directories are in user space

Keycloak "HTTPS Required" Error¶

# This was fixed in Section 4, but if it persists:

# Re-run SSL disable commands (use your actual admin password)
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password "${KEYCLOAK_ADMIN_PASSWORD}"

docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

# Also disable for the mcp-gateway realm after it's created
docker exec mcp-gateway-registry-keycloak-1 /opt/keycloak/bin/kcadm.sh update realms/mcp-gateway -s sslRequired=NONE

Services Won't Start¶

# Check Docker memory/CPU limits in Docker Desktop preferences
# Recommended: 4GB RAM, 2 CPUs minimum

# Check disk space
df -h

# Restart all services
docker-compose down
docker-compose up -d

Authentication Failures¶

# Check client secrets match
cat .oauth-tokens/keycloak-client-secrets.txt
cat .env | grep KEYCLOAK_CLIENT_SECRET

# They should match! If not, update .env file

# Restart auth-server after updating secrets
docker-compose restart auth-server

"oauth2_callback_failed" Error¶

# Check auth-server logs
docker-compose logs auth-server | tail -20

# Usually caused by wrong client secret
# Regenerate credentials:
./keycloak/setup/get-all-client-credentials.sh

# Update .env file with new secrets
nano .env

# Restart auth-server
docker-compose restart auth-server

Reset Everything¶

If you need to start over completely:

# Stop and remove all containers and data
docker-compose down -v

# Remove Docker images (optional)
docker system prune -a

# Remove generated files
rm -rf .oauth-tokens/
rm .env

# Start fresh from Section 3
cp .env.example .env

View Service Status¶

# Check all service status
docker-compose ps

# Check specific service health
docker-compose logs [service-name] --tail 50

# Check resource usage
docker stats

macOS-Specific Logs¶

# Check Console.app for system logs
# Check Docker Desktop logs via Docker Desktop > Troubleshoot > Get support

# Check local network issues
ping localhost
telnet localhost 8080

Summary¶

You now have a fully functional MCP Gateway & Registry running on macOS! The system provides:

Authentication: Enterprise-grade Keycloak identity provider
Registry: Web-based interface for managing MCP servers
API Gateway: Centralized access to multiple MCP servers
Agent Support: Ready for AI coding assistants and agents
Container Choice: Works with both Docker and Podman

Key URLs:¶

With Docker: - Registry: http://localhost - Keycloak Admin: http://localhost:8080/admin - API Gateway: http://localhost/mcpgw/mcp - Individual Services: http://localhost/[service-name]/mcp

With Podman: - Registry: http://localhost:8080 - Keycloak Admin: http://localhost:18080/admin - API Gateway: http://localhost:8080/mcpgw/mcp - Individual Services: http://localhost:8080/[service-name]/mcp

Key Files:¶

Configuration: .env
Client Credentials: .oauth-tokens/keycloak-client-secrets.txt
Agent Tokens: .oauth-tokens/agent-*-m2m.env
Podman Overlay: docker-compose.podman.yml (auto-applied with --podman flag)

Next Steps:¶

Configure your AI coding assistant with the generated MCP configuration
Create additional agents using the setup-agent-service-account.sh script
Add custom MCP servers by editing docker-compose.yml
Explore the web interface to manage servers and view metrics
Try Podman if you want rootless container deployment (see Section 10)

Remember: Save your credentials securely and keep Docker Desktop running when using the system!

Getting Help¶

GitHub Issues: https://github.com/agentic-community/mcp-gateway-registry/issues
Documentation: Check /docs folder for additional guides
Logs: Always check docker-compose logs for troubleshooting