Skip to content

✅ Developer Onboarding Checklist

Follow this checklist to set up your development environment, verify all features, and ensure consistent onboarding across the MCP Gateway project.

🛠 Environment Setup

System prerequisites
  • Python ≥ 3.11
  • Node.js and npm, npx (used for testing with supergateway and the HTML/JS Admin UI)
  • Docker, Docker Compose, and Podman
  • Make, GitHub CLI (gh), curl, jq, openssl
  • Optional: Visual Studio Code + Dev Containers extension (or WSL2 if on Windows) + Pyrefly
  • Optional: On Windows, install the WSL and Remote Development extensions
Python tooling
  • pip install --upgrade pip
  • uv and uvx installed - install uv
  • .venv recreated with make install-dev (installs runtime + dev extras)
Additional tools
  • helm installed for Kubernetes deployments (Helm install docs)
  • Security tools in $PATH: hadolint, dockle, trivy, osv-scanner
Useful VS Code extensions
  • Python, Pylance
  • YAML, Even Better TOML
  • Docker, Dev Containers (useful on Windows)
GitHub setup
.env configuration
  • Copy .env.example to .env
  • Set various env variables, such as:
    • JWT_SECRET_KEY
    • BASIC_AUTH_PASSWORD

🔧 Makefile Targets

Local setup
  • make check-env (validates .env is complete)
  • make install-dev serve
  • make smoketest runs and passes
Container builds
  • Docker: make docker-prod docker-run-ssl-host compose-up
  • Podman: make podman podman-prod podman-run-ssl-host
Packaging
  • make dist verify builds packages
  • make devpi-install devpi-init devpi-start devpi-setup-user devpi-upload devpi-test
  • Install and test mcpgateway CLI locally
Minikube & Helm
  • make helm-install minikube-install minikube-start minikube-k8s-apply helm-package helm-deploy
  • See minikube deployment

🧪 Testing

Code quality
  • make lint, make lint-web
  • make shell-linters-install, make shell-lint
  • make hadolint (Dockerfile linting)
Unit tests
  • make test passes all cases

🔐 Security

Vulnerability scans
  • Run: 
    make hadolint dockle osv-scan trivy pip-audit
SonarQube analysis
  • make sonar-up-docker
  • make sonar-submit-docker - ensure no critical violations

🔑 JWT Authentication

Generate and use a Bearer token

  • Export a token with: 

    export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 0 --secret my-test-key)

  • Verify authenticated API access: 

    curl -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version | jq

🤖 Client Integration

Run wrapper and test transports
  • Run: python3 -m mcpgateway.wrapper (stdio support)
  • Test transports:
    • Streamable HTTP
    • Server-Sent Events (SSE)
  • Optional: Integrate with Claude, Copilot, Continue (usage guide)

🧭 API Testing

Authentication required
  • Unauthenticated: 
    curl http://localhost:4444/tools
# -> should return 401 Unauthorized
  • Authenticated: 
    curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
Endpoint coverage
  • Confirm key routes:
    • /version
    • /health
    • /tools
    • /servers
    • /resources
    • /prompts
    • /gateways
  • Browse Redoc docs

🖥 Admin UI

Login and diagnostics
  • Navigate to /admin
  • Log in with Basic Auth credentials from .env
  • /version shows healthy DB and Redis
CRUD verification
  • Create / edit / delete:
    • Servers
    • Tools
    • Resources
    • Prompts
    • Gateways
  • Toggle active/inactive switches
  • JWT stored in HttpOnly cookie, no errors in DevTools Console
Metrics
  • Confirm latency and error rate display under load

📚 Documentation

Build and inspect docs
  • cd docs && make venv serve
  • Open http://localhost:8000
  • Confirm:
    • .pages ordering
    • nav structure
    • working images
    • Mermaid diagrams
Read and understand

✅ Final Review

Ready to contribute
  • All items checked
  • PR description links to this checklist
  • Stuck? Open a discussion or issue