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.

The fastest way to get started is using the VS Code Dev Container, which provides a fully-configured development environment.

Prerequisites
Setup

  1. Clone and open the repository: 

    git clone https://github.com/ibm/mcp-context-forge.git
cd mcp-context-forge
code .

  2. VS Code will detect .devcontainer and prompt: "Reopen in Container" (or manually: CtrlοΌ‹ShiftοΌ‹P β†’ Dev Containers: Reopen in Container)

  3. First-time build automatically:

    • Installs system packages & Python 3.11
    • Runs make install-dev to pull all dependencies
    • Executes tests to verify the toolchain
Daily workflow inside container 
make dev            # Dev server with hot reload (http://localhost:4444)
make test           # Run test suite
make lint           # Run all linters
GitHub Codespaces (1-click cloud IDE)

No local Docker? Use Codespaces:

  1. Go to the repo β†’ Code β–Έ Codespaces β–Έ Create codespace on main
  2. Wait for the container image to build in the cloud
  3. Develop using the same workflow above

πŸ›  Manual Environment SetupΒΆ

If not using Dev Containers, set up manually:

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 + Pyrefly extension
  • 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)
Python unit tests
  • make test passes all cases
  • make coverage generates coverage report
UI automation (Playwright)
  • playwright install (one-time browser setup)
  • pytest tests/playwright/ passes
  • pytest tests/playwright/ -k admin validates Admin UI flows
Load testing (Locust)
  • make testing-up (containerized Locust + test services)
  • Or run Locust locally: locust -f tests/loadtest/locustfile.py --host=http://localhost:4444
  • Access dashboard at http://localhost:8089
  • Verify no errors under moderate load (50-100 users)
Frontend linting
  • make eslint - JavaScript linting
  • make lint-web - ESLint + HTMLHint + Stylelint
  • make format-web - Prettier formatting
  • Note: JS unit tests not yet implemented

πŸ” 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 10080 --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