| name | macos-setup |
| description | Complete macOS setup and teardown for MCP Gateway & Registry (AI-registry). Clones the repository, installs all services, configures Keycloak auth, registers the Cloudflare docs server, and verifies the full stack. Also supports complete teardown. Can be run directly from its GitHub URL without the repository already cloned. Uses an interactive or default-values mode chosen at startup. |
| license | Apache-2.0 |
| metadata | {"author":"mcp-gateway-registry","version":"2.0"} |
MCP Gateway & Registry — macOS Setup Skill
Repository: https://github.com/agentic-community/mcp-gateway-registry
This skill: https://github.com/agentic-community/mcp-gateway-registry/blob/main/.claude/skills/macos-setup/SKILL.md
Full macOS guide: https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/macos-setup-guide.md
How to run this skill without cloning the repository
This skill is self-contained. You can invoke it from any directory in Claude Code using the GitHub URL. It will clone the repository for you.
/macos-setup
Or reference it remotely if you have not installed this repo:
@https://raw.githubusercontent.com/agentic-community/mcp-gateway-registry/main/.claude/skills/macos-setup/SKILL.md
What this skill does
/macos-setup setup — Full guided installation on a fresh macOS machine:
- Clones the MCP Gateway & Registry repository
- Installs and configures all services (Keycloak, registry, auth-server, MCP servers)
- Builds all Docker images from source
- Registers the Cloudflare Documentation MCP server so it appears immediately on login
- Ends with a complete summary of every step taken
/macos-setup teardown — Removes all MCP Gateway components from your system
CRITICAL: First action is ALWAYS Step 0
DO NOT run any Bash commands. DO NOT check prerequisites. DO NOT read any files.
The very first action when this skill is invoked MUST be using AskUserQuestion to complete Step 0.
Nothing else happens until the user has answered all three Step 0 questions.
Step tracking
Throughout the entire execution, Claude must maintain an internal step log. After every phase completes (success, skip, or failure), append an entry to this log. Display the full log as a formatted table in the Final Summary phase.
Step log format: { phase, name, status (DONE / SKIPPED / FAILED), notes }
Step 0: Determine Mode — MUST BE FIRST, NO EXCEPTIONS
STOP. Do not run any commands. Use AskUserQuestion right now to ask all three questions below before taking any other action.
Question 1 — Operation:
Which operation would you like to perform?
Setup - Install the MCP Gateway & Registry (AI-registry) from scratch.
Builds all services from source. Estimated time: 20-40 minutes.
Teardown - Stop all services and remove all components. Irreversible.
If the user invoked the skill with an argument (/macos-setup setup or /macos-setup teardown), skip this question.
Question 2 — Execution mode (Setup only):
How should I run the setup?
Default (recommended) - Use sensible defaults for all prompts. I will only
pause for decisions that truly require your input. Passwords will be
auto-generated and shown in the final summary.
Interactive - Ask for your confirmation and input before every phase.
You control each step individually.
Store the answer as EXECUTION_MODE = default or interactive.
Question 3 — Installation directory (Setup only):
Where should the AI-registry project be installed?
Default: ~/AI-registry
Enter a path, or press Enter / select the default option to use ~/AI-registry.
Store the answer as INSTALL_DIR. If the user provides no input or selects the default, set INSTALL_DIR=~/AI-registry and inform the user:
"Using default installation directory: ~/AI-registry"
Expand the path immediately:
INSTALL_DIR=$(eval echo "${INSTALL_DIR}")
echo "Installation directory: ${INSTALL_DIR}"
Log: { 0, "Mode & Directory Selection", DONE, "Mode: ${EXECUTION_MODE}, Dir: ${INSTALL_DIR}" }
SETUP WORKFLOW
For every phase below, apply this rule:
- Interactive mode: announce the phase, use
AskUserQuestion to confirm before executing
- Default mode: announce what you are doing with a one-line message, then execute immediately without asking confirmation
Phase 1: Prerequisites Check
Announce: "Checking prerequisites..."
echo "=== Docker ==="
docker --version 2>/dev/null && docker ps >/dev/null 2>&1 && echo "DOCKER_OK" || echo "DOCKER_FAIL"
echo "=== Python ==="
python3 --version 2>/dev/null && echo "PYTHON_OK" || echo "PYTHON_FAIL"
echo "=== uv ==="
uv --version 2>/dev/null && echo "UV_OK" || echo "UV_FAIL"
echo "=== Node.js (required for building from source) ==="
node --version 2>/dev/null && echo "NODE_OK" || echo "NODE_FAIL"
echo "=== git ==="
git --version 2>/dev/null && echo "GIT_OK" || echo "GIT_FAIL"
echo "=== jq ==="
jq --version 2>/dev/null && echo "JQ_OK" || echo "JQ_FAIL"
echo "=== gettext ==="
gettext --version 2>/dev/null && echo "GETTEXT_OK" || echo "GETTEXT_FAIL"
For any failed check, display the install instructions:
| Check | Install command |
|---|
| DOCKER_FAIL | "Install Docker Desktop from https://www.docker.com/products/docker-desktop/ then start it and wait for the whale icon in the menu bar" |
| PYTHON_FAIL | brew install python@3.14 |
| UV_FAIL | curl -LsSf https://astral.sh/uv/install.sh | sh — then restart your terminal |
| NODE_FAIL | brew install node@20 or download from https://nodejs.org/ |
| GIT_FAIL | xcode-select --install |
| JQ_FAIL | brew install jq |
| GETTEXT_FAIL | brew install gettext |
Do not proceed if Docker or git fail. Python, uv, Node.js, jq, and gettext must also be present before continuing. Ask the user to install missing tools and retry.
Log: { 1, "Prerequisites Check", DONE/FAILED, list of what passed/failed }
Phase 2: Clone Repository
Announce: "Cloning the MCP Gateway & Registry repository to ${INSTALL_DIR}..."
First check if the directory already exists:
if [ -d "${INSTALL_DIR}" ]; then
echo "ALREADY_EXISTS"
ls "${INSTALL_DIR}/docker-compose.yml" 2>/dev/null && echo "REPO_OK" || echo "NOT_A_REPO"
else
echo "WILL_CLONE"
fi
If ALREADY_EXISTS and REPO_OK: Inform the user and ask (both modes):
The directory ${INSTALL_DIR} already contains the repository.
Use existing - Continue setup with the existing copy
Re-clone - Remove it and clone fresh (WARNING: deletes existing data)
If WILL_CLONE: Clone the repository:
mkdir -p "$(dirname "${INSTALL_DIR}")"
git clone https://github.com/agentic-community/mcp-gateway-registry.git "${INSTALL_DIR}"
echo "Clone exit code: $?"
After cloning or confirming existing, change into the directory:
cd "${INSTALL_DIR}"
echo "Working directory: $(pwd)"
ls docker-compose.yml build_and_run.sh 2>/dev/null && echo "REPO_VERIFIED" || echo "REPO_INVALID"
All subsequent phases run commands from within ${INSTALL_DIR}.
Key files now available locally (GitHub references for documentation):
Log: { 2, "Repository Clone", DONE/SKIPPED, "Cloned to ${INSTALL_DIR} / Used existing" }
Phase 3: Credentials Configuration
Announce: "Configuring credentials..."
In default mode: Auto-generate both passwords using Python. Store them for the final summary.
KEYCLOAK_ADMIN_PASSWORD=$(python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(20)))")
KEYCLOAK_DB_PASSWORD=$(python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(20)))")
echo "Passwords auto-generated (will be shown in final summary)"
echo "Admin password length: ${#KEYCLOAK_ADMIN_PASSWORD}"
echo "DB password length: ${#KEYCLOAK_DB_PASSWORD}"
In interactive mode: Use AskUserQuestion to collect:
- Keycloak Admin Password — minimum 8 characters, REQUIRED, no default. Used to log in at
http://localhost:8080/admin.
- Keycloak Database Password — minimum 8 characters, REQUIRED, no default. Internal Keycloak database credential.
Validate: if either password is fewer than 8 characters or empty, re-prompt. Do not proceed with weak passwords.
Log: { 3, "Credentials Configuration", DONE, "default-generated / user-provided" }
Phase 4: Environment File Setup
Announce: "Creating .env configuration file..."
Check for existing .env:
ls -la "${INSTALL_DIR}/.env" 2>/dev/null && echo "ENV_EXISTS" || echo "ENV_MISSING"
In interactive mode with existing .env, ask to overwrite. In default mode, overwrite automatically and note it in the log.
cd "${INSTALL_DIR}"
cp .env.example .env
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(64))")
echo "SECRET_KEY generated: ${#SECRET_KEY} characters"
Update .env using Python to handle special characters safely:
cd "${INSTALL_DIR}"
python3 << 'PYEOF'
import re, os
env_path = '.env'
content = open(env_path).read()
updates = {
'AUTH_PROVIDER': 'keycloak',
'AUTH_SERVER_EXTERNAL_URL': 'http://localhost',
'KEYCLOAK_ADMIN_PASSWORD': os.environ.get('KEYCLOAK_ADMIN_PASSWORD', ''),
'KEYCLOAK_DB_PASSWORD': os.environ.get('KEYCLOAK_DB_PASSWORD', ''),
'SECRET_KEY': os.environ.get('SECRET_KEY', ''),
'MCP_CLOUD_PROVIDER': 'on_premises',
}
for key, value in updates.items():
pattern = rf'^{key}=.*'
replacement = f'{key}={value}'
if re.search(pattern, content, flags=re.MULTILINE):
content = re.sub(pattern, replacement, content, flags=re.MULTILINE)
else:
content += f'\n{key}={value}'
open(env_path, 'w').write(content)
print('Environment file updated successfully')
PYEOF
Verify (without exposing values):
cd "${INSTALL_DIR}"
for KEY in AUTH_PROVIDER AUTH_SERVER_EXTERNAL_URL KEYCLOAK_ADMIN_PASSWORD KEYCLOAK_DB_PASSWORD SECRET_KEY MCP_CLOUD_PROVIDER; do
VALUE=$(grep "^${KEY}=" .env | cut -d'=' -f2)
if [ -n "$VALUE" ]; then
echo "${KEY}=[set]"
else
echo "${KEY}=[MISSING - ERROR]"
fi
done
The template is at: .env.example
Log: { 4, "Environment File Setup", DONE, ".env created and configured" }
Phase 5: Python Virtual Environment
Announce: "Installing Python dependencies via uv sync..."
First, enable native TLS so that uv uses the macOS system certificate store. This is required on enterprise Macs with corporate proxies or custom CA certificates, and is harmless on personal Macs.
export UV_NATIVE_TLS=true
cd "${INSTALL_DIR}"
uv sync
echo "uv sync exit code: $?"
ls -la .venv/bin/python 2>/dev/null && echo "VENV_OK" || echo "VENV_FAIL"
Log: { 5, "Python Virtual Environment", DONE/FAILED, "" }
Phase 6: Download Embeddings Model
Announce: "Downloading sentence-transformers embeddings model (~90MB) to ~/mcp-gateway/models/..."
This model powers intelligent tool discovery. It is downloaded from HuggingFace.
mkdir -p "${HOME}/mcp-gateway/models/all-MiniLM-L6-v2"
cd "${INSTALL_DIR}"
if command -v huggingface-cli >/dev/null 2>&1; then
huggingface-cli download sentence-transformers/all-MiniLM-L6-v2 \
--local-dir "${HOME}/mcp-gateway/models/all-MiniLM-L6-v2"
else
uv run python -c "
from huggingface_hub import snapshot_download
import os
path = snapshot_download(
'sentence-transformers/all-MiniLM-L6-v2',
local_dir=os.path.expanduser('~/mcp-gateway/models/all-MiniLM-L6-v2')
)
print(f'Downloaded to: {path}')
"
fi
echo "Model files: $(ls ${HOME}/mcp-gateway/models/all-MiniLM-L6-v2/ | wc -l | tr -d ' ') files"
Log: { 6, "Embeddings Model Download", DONE/FAILED, "~/mcp-gateway/models/all-MiniLM-L6-v2" }
Phase 7: Create Required Directories
Announce: "Creating Docker volume mount directories..."
mkdir -p "${HOME}/mcp-gateway/{servers,models,auth_server,logs,ssl}"
ls -la "${HOME}/mcp-gateway/"
Log: { 7, "Directory Creation", DONE, "~/mcp-gateway/{servers,models,auth_server,logs,ssl}" }
Phase 8: Start Keycloak Services
Announce: "Starting Keycloak authentication services (1-3 minute wait)..."
cd "${INSTALL_DIR}"
export KEYCLOAK_ADMIN_PASSWORD="${KEYCLOAK_ADMIN_PASSWORD}"
export KEYCLOAK_DB_PASSWORD="${KEYCLOAK_DB_PASSWORD}"
docker compose up -d keycloak-db keycloak
echo "Docker compose exit code: $?"
Poll until Keycloak responds (max 180 seconds):
echo "Waiting for Keycloak to be ready..."
TIMEOUT=180
ELAPSED=0
READY=false
while [ $ELAPSED -lt $TIMEOUT ]; do
HTTP=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/realms/master 2>/dev/null || echo "000")
if [ "$HTTP" = "200" ]; then
echo "Keycloak ready after ${ELAPSED}s"
READY=true
break
fi
echo " ${ELAPSED}s — HTTP ${HTTP}, still waiting..."
sleep 10
ELAPSED=$((ELAPSED + 10))
done
[ "$READY" = "false" ] && echo "ERROR: Keycloak did not start within ${TIMEOUT}s" && docker compose logs keycloak --tail 20
Verify:
curl -s http://localhost:8080/realms/master | python3 -c "
import sys, json
try:
d = json.load(sys.stdin)
print('Keycloak master realm:', d.get('realm'))
except Exception as e:
print('Parse error:', e)
"
Log: { 8, "Keycloak Startup", DONE/FAILED, "Ready in Xs / timed out" }
Phase 9: Verify Keycloak SSL Posture
Announce: "Verifying Keycloak's SSL requirement (should be 'external', reachable over loopback)..."
The realms ship with sslRequired: external, which requires TLS for external
requests but allows plaintext HTTP from loopback (localhost). The setup commands
talk to Keycloak over http://localhost:8080, so no change is needed. Do NOT set
sslRequired=NONE — that disables TLS enforcement for external requests too,
allowing admin login and OIDC/token traffic over plaintext HTTP.
Detect the Keycloak container name:
KEYCLOAK_CONTAINER=$(docker ps --format "{{.Names}}" | grep keycloak | grep -v db | head -1)
echo "Keycloak container: ${KEYCLOAK_CONTAINER}"
[ -z "$KEYCLOAK_CONTAINER" ] && echo "ERROR: No Keycloak container running" && docker ps && exit 1
Confirm the master realm is reachable over loopback HTTP (external allows this):
HTTP=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:8080/admin/")
echo "Admin endpoint: HTTP ${HTTP} (302 = success)"
Log: { 9, "Keycloak SSL Posture (external, loopback OK)", DONE/FAILED, "HTTP ${HTTP}" }
Phase 10: Initialize Keycloak Realm and Clients
Announce: "Initializing Keycloak — creating mcp-gateway realm and OAuth clients..."
Script: keycloak/setup/init-keycloak.sh
cd "${INSTALL_DIR}"
chmod +x keycloak/setup/init-keycloak.sh
export KEYCLOAK_ADMIN_PASSWORD="${KEYCLOAK_ADMIN_PASSWORD}"
./keycloak/setup/init-keycloak.sh
echo "Init exit code: $?"
The newly created mcp-gateway realm ships with sslRequired: external, which
works over loopback HTTP — no SSL change is needed. Do NOT set sslRequired=NONE.
Verify both realms:
curl -s http://localhost:8080/realms/master | python3 -c "import sys,json; print('master:', json.load(sys.stdin).get('realm'))"
curl -s http://localhost:8080/realms/mcp-gateway | python3 -c "import sys,json; print('mcp-gateway:', json.load(sys.stdin).get('realm'))"
Common failures and fixes:
- If the script fails with an "HTTPS required" error: you are reaching Keycloak over a non-loopback address. Use
http://localhost:8080. Do NOT lower sslRequired to none.
- If Keycloak is not responding: wait 30 seconds and retry — it may still be initializing
- If admin credentials are rejected: verify
KEYCLOAK_ADMIN_PASSWORD matches what was set in Phase 3
Log: { 10, "Keycloak Init (realm + clients)", DONE/FAILED, "mcp-gateway realm created" }
Phase 11: Retrieve Client Credentials
Announce: "Retrieving OAuth client secrets from Keycloak and updating .env..."
Script: keycloak/setup/get-all-client-credentials.sh
cd "${INSTALL_DIR}"
chmod +x keycloak/setup/get-all-client-credentials.sh
./keycloak/setup/get-all-client-credentials.sh
echo "Credentials retrieval exit code: $?"
Parse the retrieved secrets and update .env:
cd "${INSTALL_DIR}"
WEB_SECRET=$(grep "^KEYCLOAK_CLIENT_SECRET=" .oauth-tokens/keycloak-client-secrets.txt 2>/dev/null | head -1 | cut -d'=' -f2)
M2M_SECRET=$(grep "^KEYCLOAK_M2M_CLIENT_SECRET=" .oauth-tokens/keycloak-client-secrets.txt 2>/dev/null | head -1 | cut -d'=' -f2)
echo "Web client secret: ${#WEB_SECRET} characters"
echo "M2M client secret: ${#M2M_SECRET} characters"
python3 << PYEOF
import re
content = open('.env').read()
web = '${WEB_SECRET}'
m2m = '${M2M_SECRET}'
for key, val in [('KEYCLOAK_CLIENT_SECRET', web), ('KEYCLOAK_M2M_CLIENT_SECRET', m2m)]:
if re.search(rf'^{key}=', content, flags=re.MULTILINE):
content = re.sub(rf'^{key}=.*', f'{key}={val}', content, flags=re.MULTILINE)
else:
content += f'\n{key}={val}'
open('.env', 'w').write(content)
print('Secrets written to .env')
PYEOF
Log: { 11, "Client Credentials Retrieved", DONE/FAILED, ".oauth-tokens/ populated, .env updated" }
Phase 12: Create Test Agents
Announce: "Creating service account agents for MCP Gateway access..."
Script: keycloak/setup/setup-agent-service-account.sh
cd "${INSTALL_DIR}"
chmod +x keycloak/setup/setup-agent-service-account.sh
export KEYCLOAK_ADMIN_PASSWORD="${KEYCLOAK_ADMIN_PASSWORD}"
echo "Creating test-agent..."
./keycloak/setup/setup-agent-service-account.sh \
--agent-id test-agent \
--group mcp-servers-unrestricted
echo "test-agent exit code: $?"
echo "Creating ai-coding-assistant..."
./keycloak/setup/setup-agent-service-account.sh \
--agent-id ai-coding-assistant \
--group mcp-servers-unrestricted
echo "ai-coding-assistant exit code: $?"
./keycloak/setup/get-all-client-credentials.sh
echo "Credentials refreshed"
ls .oauth-tokens/
Log: { 12, "Test Agents Created", DONE/FAILED, "test-agent, ai-coding-assistant" }
Phase 13: Build and Start All Services
Announce: "Building all Docker images from source and starting all services. This builds the React frontend and all containers locally — this will take 20-40 minutes on first run."
Script: build_and_run.sh
cd "${INSTALL_DIR}"
chmod +x build_and_run.sh
./build_and_run.sh
echo "build_and_run.sh exit code: $?"
After the build completes, wait for services to initialize:
echo "Waiting 30 seconds for all services to start..."
sleep 30
echo "=== Service Status ==="
docker compose ps
echo "=== Health Checks ==="
for URL in "http://localhost/health" "http://localhost/" "http://localhost:8080/realms/mcp-gateway"; do
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${URL}" 2>/dev/null || echo "000")
echo " ${URL}: HTTP ${STATUS}"
done
If services are not healthy, show logs:
docker compose logs registry --tail 20
docker compose logs auth-server --tail 20
Log: { 13, "Build and Start All Services", DONE/FAILED, "Build time: ~Xmin, services: up/partial" }
Phase 14: Generate Access Tokens
Announce: "Generating access tokens for all agents..."
Script: credentials-provider/keycloak/get_m2m_token.py
cd "${INSTALL_DIR}"
uv run credentials-provider/keycloak/get_m2m_token.py --all-agents 2>/dev/null
echo "Token generation exit code: $?"
echo "=== Available token files ==="
ls .oauth-tokens/*.env 2>/dev/null | head -10
Log: { 14, "Access Token Generation", DONE/FAILED, "Tokens in .oauth-tokens/" }
Phase 15: Register Cloudflare Documentation Server
Announce: "Registering Cloudflare Documentation MCP Server so it appears immediately on login..."
Config file: cli/examples/cloudflare-docs-server-config.json
Registration CLI: api/registry_management.py
cd "${INSTALL_DIR}"
TOKEN_FILE=".oauth-tokens/agent-test-agent-m2m-token.json"
if [ ! -f "$TOKEN_FILE" ]; then
echo "ERROR: Token file not found: $TOKEN_FILE"
ls .oauth-tokens/
exit 1
fi
echo "Token file found: ${TOKEN_FILE}"
uv run python api/registry_management.py \
--token-file "${TOKEN_FILE}" \
--registry-url http://localhost \
register \
--config cli/examples/cloudflare-docs-server-config.json \
--overwrite
echo "Cloudflare registration exit code: $?"
Verify the server was registered:
cd "${INSTALL_DIR}"
uv run python api/registry_management.py \
--token-file ".oauth-tokens/agent-test-agent-m2m-token.json" \
--registry-url http://localhost \
list 2>/dev/null | grep -i cloudflare && echo "Cloudflare server confirmed in registry" || echo "WARNING: Cloudflare server not found in list"
The server configuration that was registered:
{
"server_name": "Cloudflare Documentation MCP Server",
"description": "Search Cloudflare documentation and get migration guides",
"path": "/cloudflare-docs",
"proxy_pass_url": "https://docs.mcp.cloudflare.com/mcp",
"supported_transports": ["streamable-http"],
"tags": ["documentation", "cloudflare", "cdn", "workers", "pages", "migration-guide"]
}
Log: { 15, "Cloudflare Server Registration", DONE/FAILED, "Registered at /cloudflare-docs" }
Phase 16: Final Verification and Summary
Announce: "Running final verification and preparing your summary..."
cd "${INSTALL_DIR}"
echo "=== All Services ==="
docker compose ps
echo ""
echo "=== Endpoint Health ==="
declare -A ENDPOINTS=(
["Main UI"]="http://localhost/"
["Registry Health"]="http://localhost/health"
["Keycloak mcp-gateway realm"]="http://localhost:8080/realms/mcp-gateway"
["Cloudflare MCP endpoint"]="http://localhost/cloudflare-docs/mcp"
)
for NAME in "${!ENDPOINTS[@]}"; do
URL="${ENDPOINTS[$NAME]}"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${URL}" 2>/dev/null || echo "000")
echo " ${NAME}: ${URL} — HTTP ${STATUS}"
done
echo ""
echo "=== Registered Servers ==="
uv run python api/registry_management.py \
--token-file ".oauth-tokens/agent-test-agent-m2m-token.json" \
--registry-url http://localhost \
list 2>/dev/null || echo "Could not retrieve server list"
Display the complete step summary table:
Present a formatted summary of every phase from the internal step log:
========================================
AI-REGISTRY SETUP COMPLETE
========================================
Installation Directory: ${INSTALL_DIR}
Step Summary:
+-------+--------------------------------------------+----------+-----------------------------+
| Phase | Name | Status | Notes |
+-------+--------------------------------------------+----------+-----------------------------+
| 0 | Mode & Directory Selection | DONE | mode, dir |
| 1 | Prerequisites Check | DONE | all passed |
| 2 | Repository Clone | DONE | ${INSTALL_DIR} |
| 3 | Credentials Configuration | DONE | default-generated/provided |
| 4 | Environment File Setup | DONE | .env configured |
| 5 | Python Virtual Environment | DONE | .venv created |
| 6 | Embeddings Model Download | DONE | ~90MB downloaded |
| 7 | Directory Creation | DONE | ~/mcp-gateway/... |
| 8 | Keycloak Startup | DONE | ready in Xs |
| 9 | Keycloak SSL Posture (external) | DONE | loopback HTTP reachable |
| 10 | Keycloak Init (realm + clients) | DONE | mcp-gateway realm |
| 11 | Client Credentials Retrieved | DONE | .oauth-tokens/ updated |
| 12 | Test Agents Created | DONE | test-agent, ai-assistant |
| 13 | Build and Start All Services | DONE | all containers up |
| 14 | Access Token Generation | DONE | .oauth-tokens/*.env |
| 15 | Cloudflare Server Registration | DONE | /cloudflare-docs |
| 16 | Final Verification | DONE | all checks passed |
+-------+--------------------------------------------+----------+-----------------------------+
Access Points:
Main UI (login here): http://localhost
Keycloak Admin: http://localhost:8080/admin
Registry API: http://localhost/health
MCP Gateway: http://localhost/mcpgw/mcp
Cloudflare MCP server: http://localhost/cloudflare-docs/mcp
Login Credentials:
URL: http://localhost
Username: admin
Password: [KEYCLOAK_ADMIN_PASSWORD shown only in default mode — see below]
Agent Credentials:
Test agent: ${INSTALL_DIR}/.oauth-tokens/agent-test-agent-m2m.env
AI assistant: ${INSTALL_DIR}/.oauth-tokens/agent-ai-coding-assistant-m2m.env
Registered Servers:
- Cloudflare Documentation MCP Server (/cloudflare-docs) — visible immediately on login
Quick Test:
cd ${INSTALL_DIR}
source .venv/bin/activate
source .oauth-tokens/agent-test-agent-m2m.env
uv run cli/mcp_client.py ping
In default mode only, display the auto-generated passwords clearly since the user never set them:
Generated Credentials (SAVE THESE):
Keycloak Admin Password: ${KEYCLOAK_ADMIN_PASSWORD}
Keycloak DB Password: ${KEYCLOAK_DB_PASSWORD}
These passwords are also stored in: ${INSTALL_DIR}/.env
TEARDOWN WORKFLOW
Phase T1: Confirm Scope
Use AskUserQuestion (always, regardless of mode) to ask:
Required confirmation:
This will permanently remove:
- All running MCP Gateway Docker containers
- All Docker volumes (Keycloak config, database — IRREVERSIBLE)
- .env configuration file
- .oauth-tokens/ directory
This cannot be undone. Proceed?
Also ask:
- Remove model files at
~/mcp-gateway/? (Yes / No)
- Remove cached Docker images? (Yes / No)
Only proceed if the user explicitly confirms.
Phase T2: Stop All Services and Remove Volumes
INSTALL_DIR="${INSTALL_DIR:-~/AI-registry}"
INSTALL_DIR=$(eval echo "${INSTALL_DIR}")
cd "${INSTALL_DIR}" 2>/dev/null || echo "Directory not found, skipping cd"
docker compose down -v 2>/dev/null || docker-compose down -v 2>/dev/null || echo "No services were running"
docker ps | grep -E "keycloak|registry|auth-server|nginx|mcpgw|currenttime" \
&& echo "WARNING: some containers still running" \
|| echo "All MCP Gateway containers stopped"
Phase T3: Remove Generated Files
cd "${INSTALL_DIR}" 2>/dev/null || true
rm -rf .oauth-tokens/ && echo "Removed .oauth-tokens/"
rm -f .env && echo "Removed .env"
Phase T4: Remove Model Files (if selected)
rm -rf "${HOME}/mcp-gateway/" && echo "Removed ~/mcp-gateway/"
Phase T5: Remove Docker Images (if selected)
docker images | grep -E "mcpgateway|mcp-gateway-registry" | awk '{print $3}' | sort -u | xargs -r docker rmi -f
echo "Docker image removal complete"
Phase T6: Teardown Summary
echo "=== Remaining containers ==="
docker ps -a | grep -E "keycloak|registry|auth-server" || echo "None"
echo "=== Remaining volumes ==="
docker volume ls | grep -E "mcp.gateway|keycloak" || echo "None"
echo "=== Files ==="
ls "${INSTALL_DIR}/.env" 2>/dev/null && echo "WARNING: .env still exists" || echo ".env removed"
ls -d "${INSTALL_DIR}/.oauth-tokens/" 2>/dev/null && echo "WARNING: .oauth-tokens/ still exists" || echo ".oauth-tokens/ removed"
Present final teardown summary to the user listing everything that was removed.
Error Handling Reference
Docker not running
"Docker Desktop is not running. Open it from Applications and wait for the whale icon in the menu bar."
Port conflict
lsof -i :80 && echo "Port 80 in use"
lsof -i :8080 && echo "Port 8080 in use"
Keycloak container name varies
Always detect dynamically:
KEYCLOAK_CONTAINER=$(docker ps --format "{{.Names}}" | grep keycloak | grep -v db | head -1)
init-keycloak.sh fails
- Check logs:
docker compose logs keycloak --tail 30
- Re-run Phase 9 SSL fix
- Verify Keycloak is responding:
curl -s http://localhost:8080/realms/master
- Retry Phase 10
TLS certificate errors with uv
On enterprise Macs with corporate proxies or custom CA certificates, uv may fail with TLS errors. The setup already sets export UV_NATIVE_TLS=true in Phase 5, but if the error occurs in a later shell session, re-export it:
export UV_NATIVE_TLS=true
Cloudflare registration fails
- Verify services are healthy:
docker compose ps
- Verify token file exists and is valid
- Check registry logs:
docker compose logs registry --tail 20
- Retry:
uv run python api/registry_management.py --token-file .oauth-tokens/agent-test-agent-m2m.env --registry-url http://localhost register --config cli/examples/cloudflare-docs-server-config.json --overwrite
Important Rules
- EXECUTION_MODE and INSTALL_DIR must be established in Step 0 before any other phase runs
- In default mode: execute phases immediately after a brief announcement, no confirmation prompts — the only questions asked are in Step 0
- In interactive mode: use
AskUserQuestion before each phase
- Never display passwords in output except in the Final Summary for default-mode auto-generated passwords
- All commands run from within
${INSTALL_DIR} — cd "${INSTALL_DIR}" at the start of every phase that runs commands
- NO
--prebuilt flag on build_and_run.sh — always build from source
- Carry
KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_DB_PASSWORD, KEYCLOAK_CONTAINER, INSTALL_DIR, EXECUTION_MODE across all phases — re-export shell variables at the start of any phase that uses them
- macOS
sed syntax: always sed -i '', never sed -i — or use the Python .env update approach
- Log every phase to the internal step log and display the full table in Phase 16
