Development¶

Welcome! This guide is for developers contributing to MCP Gateway. Whether you're fixing bugs, adding features, or extending federation or protocol support, this doc will help you get up and running quickly and consistently.

🧰 What You'll Find Here¶

Page	Description
Building Locally	How to install dependencies, set up a virtual environment, and run the gateway
Packaging	How to build a release, container image, or prebuilt binary
Doctest Coverage	Comprehensive doctest coverage implementation and guidelines
DEVELOPING.md	Coding standards, commit conventions, and review workflow

🛠 Developer Environment¶

MCP Gateway is built with:

Python 3.11+
FastAPI + SQLAlchemy (async) + Pydantic Settings
HTMX, Alpine.js, TailwindCSS for the Admin UI

Development tools:

Linters: ruff, mypy, black, isort
Testing: pytest, httpx
Serving: uvicorn, gunicorn

Code style and consistency is enforced via:

make lint          # runs ruff, mypy, black, isort
make pre-commit    # runs pre-commit hooks on staged files

As well as GitHub Actions code scanning.

🧪 Testing¶

Test coverage includes:

Unit tests under tests/unit/
Integration tests under tests/integration/
End-to-end tests under tests/e2e/
Example payload performance testing under tests/hey/

Use:

make test                  # run full suite
python3 -m pytest tests/unit     # run only unit tests
python3 -m pytest tests/e2e      # run end-to-end scenarios

🔍 Linting and Hooks¶

CI will fail your PR if code does not pass lint checks.

You should manually run:

make lint
make pre-commit

Enable hooks with:

pre-commit install

🐳 Containers¶

Build and run with Podman or Docker:

make podman            # build production image
make podman-run-ssl    # run with self-signed TLS at https://localhost:4444

🔐 Authentication¶

Admin UI and API are protected by Basic Auth or JWT.

To generate a JWT token:

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

Then test:

curl -sX GET \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  http://localhost:4444/tools | jq

📦 Configuration¶

Edit .env or set environment variables. A complete list is documented in the README.

Use:

cp .env.example .env

Key configs include:

Variable	Purpose
`DATABASE_URL`	Database connection
`JWT_SECRET_KEY`	Signing key for JWTs
`DEV_MODE=true`	Enables relaxed development defaults (set together with `RELOAD=true` if you rely on `run.sh`)
`CACHE_TYPE=memory`	Options: memory, redis, none

🚧 Contribution Tips¶

Pick a good first issue
Read the CONTRIBUTING.md
Fork, branch, commit with purpose
Submit PRs against main with clear titles and linked issues

✅ CI/CD¶

GitHub Actions enforce:

CodeQL security scanning
Pre-commit linting
Dependency audits
Docker image builds

CI configs live in .github/workflows/.