Skip to content

🚢 Deploying the MCP Gateway Stack with Argo CD

This guide shows how to operate the MCP Gateway Stack with a Git-Ops workflow powered by Argo CD. Once wired up, every commit to the repository becomes an automatic deployment (or rollback) to your Kubernetes cluster.

🌳 Git source of truth: https://github.com/IBM/mcp-context-forge

  • App manifests: deployment/k8s/ (Kustomize-ready)
  • Helm chart (optional): charts/mcp-stack

📋 Prerequisites

Requirement Notes
Kubernetes ≥ 1.23 Local (Minikube/kind) or managed (EKS, AKS, GKE, etc.)
Argo CD ≥ 2.7 Server & CLI (this guide installs server into the cluster)
kubectl Configured to talk to the target cluster
Git access The cluster must be able to pull the repo (public or deploy-key)

🛠 Step 1 - Install Argo CD (once per cluster)

# Namespace + core components
kubectl create namespace argocd
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for the server component
kubectl -n argocd rollout status deploy/argocd-server

Install the CLI

# macOS
brew install argocd

# Linux (single-binary)
curl -sSL -o /tmp/argocd \
  https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 /tmp/argocd /usr/local/bin/argocd

Verify:

argocd version --client

🔐 Step 2 - Initial Login

Forward the API/UI to your workstation (leave running):

kubectl -n argocd port-forward svc/argocd-server 8083:443

Fetch the one-time admin password and log in:

PASS="$(kubectl -n argocd get secret argocd-initial-admin-secret \
          -o jsonpath='{.data.password}' | base64 -d)"
argocd login localhost:8083 \
  --username admin --password "$PASS" --insecure

Open the web UI → http://localhost:8083 (credentials above).

🚀 Step 3 - Bootstrap the Application

Create an Argo CD Application that tracks the deployment/k8s/ folder from the main branch:

APP=mcp-gateway
REPO=https://github.com/IBM/mcp-context-forge.git

argocd app create "$APP" \
  --repo "$REPO" \
  --path k8s \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --sync-policy automated \
  --revision main

Trigger the first sync:

argocd app sync "$APP"

Argo CD will apply all manifests and keep them in the Synced 🌿 / Healthy 💚 state.

✅ Step 4 - Verify Deployment

kubectl get pods,svc,ingress
argocd app list
argocd app get mcp-gateway

If using the sample Ingress:

curl http://gateway.local/health

Otherwise, port-forward:

kubectl port-forward svc/mcp-context-forge 8080:80 &
curl http://localhost:8080/health

🔄 Day-2 Operations

Sync after a new commit

argocd app sync mcp-gateway

View diff before syncing

argocd app diff mcp-gateway

Roll back to a previous revision

argocd app history mcp-gateway
argocd app rollback mcp-gateway <REVISION>

Disable / enable auto-sync

# Pause auto-sync
a rgocd app set mcp-gateway --sync-policy none
# Re-enable
argocd app set mcp-gateway --sync-policy automated

🧹 Uninstall

# Delete the application (leaves cluster objects intact)
argocd app delete mcp-gateway --yes

# Remove Argo CD completely\ nkubectl delete ns argocd

🧰 Makefile Shortcuts

The repository ships with ready-made targets:

Target Action
make argocd-install Installs Argo CD server into the current cluster
make argocd-forward Port-forwards UI/API on http://localhost:8083
make argocd-app-bootstrap Creates & auto-syncs the mcp-gateway application
make argocd-app-sync Forces a manual sync

Run make help to list them all.

🧯 Troubleshooting

Symptom Fix
ImagePullBackOff Check image name / pull secret & that the repo is public or credentials are configured in Argo CD
SyncFailed argocd app logs mcp-gateway for details; often due to immutable fields
Web UI 404 Ensure argocd-forward is still running, or expose via Ingress/LoadBalancer
RBAC denied Argo CD needs ClusterRoleBinding for non-default namespaces - see docs

📚 Further Reading