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 created with make venv install install-dev
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 venv install 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 --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