+
-* [Quick Start Guide](overview/quick_start.md)
-* [Features Overview](overview/features.md)
-* [Admin UI Walk-through](overview/ui.md)
-* [Using the `mcpgateway-wrapper`](using/mcpgateway-wrapper.md)
-* [Deployment Options](deployment/index.md)
+---
+
+โ๏ธ Docker/Podman tips
+ +* **.env files** - Put all the `-e FOO=` lines into a file and replace them with `--env-file .env`. See the provided [.env.example](.env.example) for reference. +* **Pinned tags** - Use an explicit version (e.g. `v0.5.0`) instead of `latest` for reproducible builds. +* **JWT tokens** - Generate one in the running container: + + ```bash + docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token -u admin -e 10080 --secret my-test-key + ``` +* **Upgrades** - Stop, remove, and rerun with the same `-v $(pwd)/data:/data` mount; your DB and config stay intact. -Jump straight to: +
+
---
-## Authors and Contributors
+๐ Smoke-test the running container
-!!! note - Source โ [https://github.com/IBM/mcp-context-forge](https://github.com/IBM/mcp-context-forge) +```bash +curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/health | jq +curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/tools | jq +curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/version | jq +``` - Docs โ [https://ibm.github.io/mcp-context-forge/](https://ibm.github.io/mcp-context-forge/) +
+
+
+---
+
+## Testing `mcpgateway.wrapper` by hand:
+
+Because the wrapper speaks JSON-RPC over stdin/stdout, you can interact with it using nothing more than a terminal or pipes.
+
+```bash
+# Start the MCP Gateway Wrapper
+export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
+export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/YOUR_SERVER_UUID
+python3 -m mcpgateway.wrapper
+```
+
+๐ง Running the MCP Gateway stdio wrapper
+ +The `mcpgateway.wrapper` lets you connect to the gateway over **stdio** while keeping JWT authentication. You should run this from the MCP Client. The example below is just for testing. + +```bash +# Set environment variables +export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key) +export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} +export MCP_SERVER_CATALOG_URLS='http://localhost:4444/servers/UUID_OF_SERVER_1' +export MCP_TOOL_CALL_TIMEOUT=120 +export MCP_WRAPPER_LOG_LEVEL=DEBUG # or OFF to disable logging + +docker run --rm -i \ + -e MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN \ + -e MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1 \ + -e MCP_TOOL_CALL_TIMEOUT=120 \ + -e MCP_WRAPPER_LOG_LEVEL=DEBUG \ + ghcr.io/ibm/mcp-context-forge:0.5.0 \ + python3 -m mcpgateway.wrapper +``` + +
+
+
+Initialize the protocol
+ +```json +# Initialize the protocol +{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"demo","version":"0.0.1"}}} + +# Then after the reply: +{"jsonrpc":"2.0","method":"notifications/initialized","params":{}} + +# Get prompts +{"jsonrpc":"2.0","id":4,"method":"prompts/list"} +{"jsonrpc":"2.0","id":5,"method":"prompts/get","params":{"name":"greeting","arguments":{"user":"Bob"}}} + +# Get resources +{"jsonrpc":"2.0","id":6,"method":"resources/list"} +{"jsonrpc":"2.0","id":7,"method":"resources/read","params":{"uri":"https://example.com/some.txt"}} + +# Get / call tools +{"jsonrpc":"2.0","id":2,"method":"tools/list"} +{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_system_time","arguments":{"timezone":"Europe/Dublin"}}} +``` + +
+
+
+### ๐งฉ Running from an MCP Client (`mcpgateway.wrapper`)
+
+The `mcpgateway.wrapper` exposes everything your Gateway knows about over **stdio**, so any MCP client that *can't* (or *shouldn't*) open an authenticated SSE stream still gets full tool-calling power.
+
+> **Remember** to substitute your real Gateway URL (and server ID) for `http://localhost:4444/servers/UUID_OF_SERVER_1`.
+> When inside Docker/Podman, that often becomes `http://host.docker.internal:4444/servers/UUID_OF_SERVER_1` (macOS/Windows) or the gateway container's hostname (Linux).
+
+---
+
+Expected responses from mcpgateway.wrapper
+ +```json +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"mcpgateway-wrapper","version":"0.5.0"}}} + +# When there's no tools +{"jsonrpc":"2.0","id":2,"result":{"tools":[]}} + +# After you add some tools and create a virtual server +{"jsonrpc":"2.0","id":2,"result":{"tools":[{"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"description":"Convert time between different timezones","inputSchema":{"properties":{"source_timezone":{"description":"Source IANA timezone name","type":"string"},"target_timezone":{"description":"Target IANA timezone name","type":"string"},"time":{"description":"Time to convert in RFC3339 format or common formats like '2006-01-02 15:04:05'","type":"string"}},"required":["time","source_timezone","target_timezone"],"type":"object"},"name":"convert_time"},{"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"description":"Get current system time in specified timezone","inputSchema":{"properties":{"timezone":{"description":"IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC","type":"string"}},"type":"object"},"name":"get_system_time"}]}} + +# Running the time tool: +{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"2025-07-09T00:09:45+01:00"}]}} +``` + +
+
+
+---
+
+๐ณ Docker / Podman
+ +```bash +docker run -i --rm \ + --network=host \ + -e MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \ + -e MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \ + -e MCP_TOOL_CALL_TIMEOUT=120 \ + ghcr.io/ibm/mcp-context-forge:0.5.0 \ + python3 -m mcpgateway.wrapper +``` + +
+",
+ "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
+ "MCP_TOOL_CALL_TIMEOUT": "120"
+ }
+ }
+ }
+}
+```
+
+
+
+---
+
+๐ฆ pipx (one-liner install & run)
+ +```bash +# Install gateway package in its own isolated venv +pipx install --include-deps mcp-contextforge-gateway + +# Run the stdio wrapper +MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \ +MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \ +python3 -m mcpgateway.wrapper +# Alternatively with uv +uv run --directory . -m mcpgateway.wrapper +``` + +**Claude Desktop JSON** (uses the host Python that pipx injected): + +```json +{ + "mcpServers": { + "mcpgateway-wrapper": { + "command": "python3", + "args": ["-m", "mcpgateway.wrapper"], + "env": { + "MCP_AUTH_TOKEN": "
+",
+ "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1"
+ }
+ }
+}
+```
+
+
+
+---
+
+### ๐ Using with Claude Desktop (or any GUI MCP client)
+
+1. **Edit Config** โ `File โธ Settings โธ Developer โธ Edit Config`
+2. Paste one of the JSON blocks above (Docker / pipx / uvx).
+3. Restart the app so the new stdio server is spawned.
+4. Open logs in the same menu to verify `mcpgateway-wrapper` started and listed your tools.
+
+Need help? See:
+
+* **MCP Debugging Guide** - [https://modelcontextprotocol.io/docs/tools/debugging](https://modelcontextprotocol.io/docs/tools/debugging)
+
+---
+
+## ๐ Quick Start: VS Code Dev Container
+
+Spin up a fully-loaded dev environment (Python 3.11, Docker/Podman CLI, all project dependencies) in just two clicks.
+
+---
+
+โก uv / uvx (light-speed venvs)
+ +#### 1 - Installuv (uvx is an alias it provides)
+
+```bash
+# (a) official one-liner
+curl -Ls https://astral.sh/uv/install.sh | sh
+
+# (b) or via pipx
+pipx install uv
+```
+
+#### 2 - Create an on-the-spot venv & run the wrapper
+
+```bash
+# Create venv in ~/.venv/mcpgateway (or current dir if you prefer)
+uv venv ~/.venv/mcpgateway
+source ~/.venv/mcpgateway/bin/activate
+
+# Install the gateway package using uv
+uv pip install mcp-contextforge-gateway
+
+# Launch wrapper
+MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
+MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \
+uv run --directory . -m mcpgateway.wrapper # Use this just for testing, as the Client will run the uv command
+```
+
+#### Claude Desktop JSON (runs through **uvx**)
+
+```json
+{
+ "mcpServers": {
+ "mcpgateway-wrapper": {
+ "command": "uvx",
+ "args": [
+ "run",
+ "--",
+ "python",
+ "-m",
+ "mcpgateway.wrapper"
+ ],
+ "env": {
+ "MCP_AUTH_TOKEN": "
+
+
+๐ Prerequisites
+ +* **VS Code** with the [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers) +* **Docker** or **Podman** installed and running locally + +
+
+
+๐งฐ Setup Instructions
+ +### 1 - Clone & Open + +```bash +git clone https://github.com/ibm/mcp-context-forge.git +cd mcp-context-forge +code . +``` + +VS Code will detect the `.devcontainer` and prompt: +**"Reopen in Container"** +*or* manually run: Ctrl/Cmd โง P โ **Dev Containers: Reopen in Container** + +--- + +### 2 - First-Time Build (Automatic) + +The container build will: + +* Install system packages & Python 3.11 +* Run `make install-dev` to pull all dependencies +* Execute tests to verify the toolchain + +You'll land in `/workspace` ready to develop. + +
+
+
+๐ ๏ธ Daily Developer Workflow
+ +Common tasks inside the container: + +```bash +# Start dev server (hot reload) +make dev # http://localhost:4444 + +# Run tests & linters +make test +make lint +``` + +Optional: + +* `make bash` - drop into an interactive shell +* `make clean` - clear build artefacts & caches +* Port forwarding is automatic (customize via `.devcontainer/devcontainer.json`) + +
+
+
+---
+
+## Quick Start (manual install)
+
+### Prerequisites
+
+* **Python โฅ 3.10**
+* **GNU Make** (optional, but all common workflows are available as Make targets)
+* Optional: **Docker / Podman** for containerized runs
+
+### One-liner (dev)
+
+```bash
+make venv install serve
+```
+
+What it does:
+
+1. Creates / activates a `.venv` in your home folder `~/.venv/mcpgateway`
+2. Installs the gateway and necessary dependencies
+3. Launches **Gunicorn** (Uvicorn workers) on [http://localhost:4444](http://localhost:4444)
+
+For development, you can use:
+
+```bash
+make install-dev # Install development dependencies, ex: linters and test harness
+make lint # optional: run style checks (ruff, mypy, etc.)
+```
+
+### Containerized (self-signed TLS)
+
+## Container Runtime Support
+
+This project supports both Docker and Podman. The Makefile automatically detects
+which runtime is available and handles image naming differences.
+
+### Auto-detection
+```bash
+make container-build # Uses podman if available, otherwise docker
+
+> You can use docker or podman, ex:
+
+```bash
+make podman # build production image
+make podman-run-ssl # run at https://localhost:4444
+# or listen on port 4444 on your host directly, adds --network=host to podman
+make podman-run-ssl-host
+```
+
+### Smoke-test the API
+
+```bash
+curl -k -sX GET \
+ -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+ https://localhost:4444/tools | jq
+```
+
+You should receive `[]` until you register a tool.
+
+---
+
+## Installation
+
+### Via Make
+
+```bash
+make venv install # create .venv + install deps
+make serve # gunicorn on :4444
+```
+
+### UV (alternative)
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e '.[dev]' # IMPORTANT: in zsh, quote to disable glob expansion!
+```
+
+### pip (alternative)
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Optional (PostgreSQL adapter)
+
+You can configure the gateway with SQLite, PostgreSQL (or any other compatible database) in .env.
+
+When using PostgreSQL, you need to install `psycopg2` driver.
+
+```bash
+uv pip install psycopg2-binary # dev convenience
+# or
+uv pip install psycopg2 # production build
+```
+
+#### Quick Postgres container
+
+```bash
+docker run --name mcp-postgres \
+ -e POSTGRES_USER=postgres \
+ -e POSTGRES_PASSWORD=mysecretpassword \
+ -e POSTGRES_DB=mcp \
+ -p 5432:5432 -d postgres
+```
+
+A `make compose-up` target is provided along with a [docker-compose.yml](docker-compose.yml) file to make this process simpler.
+
+---
+
+## Configuration (`.env` or env vars)
+
+> โ ๏ธ If any required `.env` variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.
+
+You can get started by copying the provided [.env.example](.env.example) to `.env` and making the necessary edits to fit your environment.
+
+โ๏ธ 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 + +
+`)
+> * Generate tokens via:
+>
+> ```bash
+> export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key)
+> echo $MCPGATEWAY_BEARER_TOKEN
+> ```
+> * Tokens allow non-interactive API clients to authenticate securely.
+>
+> ๐งช Set `AUTH_REQUIRED=false` during development if you want to disable all authentication (e.g. for local testing or open APIs) or clients that don't support SSE authentication.
+> In production, you should use the SSE to stdio `mcpgateway-wrapper` for such tools that don't support authenticated SSE, while still ensuring the gateway uses authentication.
+>
+> ๐ `AUTH_ENCRYPTION_SECRET` is used to encrypt and decrypt tool authentication credentials (`auth_value`).
+> You must set the same value across environments to decode previously stored encrypted auth values.
+> Recommended: use a long, random string.
+
+### UI Features
+
+| Setting | Description | Default | Options |
+| ------------------------------ | -------------------------------------- | ------- | ------- |
+| `MCPGATEWAY_UI_ENABLED` | Enable the interactive Admin dashboard | `false` | bool |
+| `MCPGATEWAY_ADMIN_API_ENABLED` | Enable API endpoints for admin ops | `false` | bool |
+| `MCPGATEWAY_BULK_IMPORT_ENABLED` | Enable bulk import endpoint for tools | `true` | bool |
+
+> ๐ฅ๏ธ Set both UI and Admin API to `false` to disable management UI and APIs in production.
+> ๐ฅ The bulk import endpoint allows importing up to 200 tools in a single request via `/admin/tools/import`.
+
+### Security
+
+| Setting | Description | Default | Options |
+| ------------------------- | ------------------------------ | ---------------------------------------------- | ---------- |
+| `SKIP_SSL_VERIFY` | Skip upstream TLS verification | `false` | bool |
+| `ENVIRONMENT` | Deployment environment (affects security defaults) | `development` | `development`/`production` |
+| `APP_DOMAIN` | Domain for production CORS origins | `localhost` | string |
+| `ALLOWED_ORIGINS` | CORS allow-list | Auto-configured by environment | JSON array |
+| `CORS_ENABLED` | Enable CORS | `true` | bool |
+| `CORS_ALLOW_CREDENTIALS` | Allow credentials in CORS | `true` | bool |
+| `SECURE_COOKIES` | Force secure cookie flags | `true` | bool |
+| `COOKIE_SAMESITE` | Cookie SameSite attribute | `lax` | `strict`/`lax`/`none` |
+| `SECURITY_HEADERS_ENABLED` | Enable security headers middleware | `true` | bool |
+| `X_FRAME_OPTIONS` | X-Frame-Options header value | `DENY` | `DENY`/`SAMEORIGIN` |
+| `HSTS_ENABLED` | Enable HSTS header | `true` | bool |
+| `HSTS_MAX_AGE` | HSTS max age in seconds | `31536000` | int |
+| `REMOVE_SERVER_HEADERS` | Remove server identification | `true` | bool |
+| `DOCS_ALLOW_BASIC_AUTH` | Allow Basic Auth for docs (in addition to JWT) | `false` | bool |
+
+> **CORS Configuration**: When `ENVIRONMENT=development`, CORS origins are automatically configured for common development ports (3000, 8080, gateway port). In production, origins are constructed from `APP_DOMAIN` (e.g., `https://yourdomain.com`, `https://app.yourdomain.com`). You can override this by explicitly setting `ALLOWED_ORIGINS`.
+>
+> **Security Headers**: The gateway automatically adds configurable security headers to all responses including CSP, X-Frame-Options, X-Content-Type-Options, X-Download-Options, and HSTS (on HTTPS). All headers can be individually enabled/disabled. Sensitive server headers are removed.
+>
+> **iframe Embedding**: By default, `X-Frame-Options: DENY` prevents iframe embedding for security. To allow embedding, set `X_FRAME_OPTIONS=SAMEORIGIN` (same domain) or disable with `X_FRAME_OPTIONS=""`. Also update CSP `frame-ancestors` directive if needed.
+>
+> **Cookie Security**: Authentication cookies are automatically configured with HttpOnly, Secure (in production), and SameSite attributes for CSRF protection.
+>
+> Note: do not quote the ALLOWED_ORIGINS values, this needs to be valid JSON, such as:
+> ALLOWED_ORIGINS=["http://localhost", "http://localhost:4444"]
+>
+> Documentation endpoints (`/docs`, `/redoc`, `/openapi.json`) are always protected by authentication.
+> By default, they require Bearer token authentication. Setting `DOCS_ALLOW_BASIC_AUTH=true` enables HTTP Basic Authentication as an additional method using the same credentials as `BASIC_AUTH_USER` and `BASIC_AUTH_PASSWORD`.
+
+
+### Logging
+
+MCP Gateway provides flexible logging with **stdout/stderr output by default** and **optional file-based logging**. When file logging is enabled, it provides JSON formatting for structured logs and text formatting for console output.
+
+| Setting | Description | Default | Options |
+| ----------------------- | ---------------------------------- | ----------------- | -------------------------- |
+| `LOG_LEVEL` | Minimum log level | `INFO` | `DEBUG`...`CRITICAL` |
+| `LOG_FORMAT` | Console log format | `json` | `json`, `text` |
+| `LOG_TO_FILE` | **Enable file logging** | **`false`** | **`true`, `false`** |
+| `LOG_FILE` | Log filename (when enabled) | `null` | `mcpgateway.log` |
+| `LOG_FOLDER` | Directory for log files | `null` | `logs`, `/var/log/gateway` |
+| `LOG_FILEMODE` | File write mode | `a+` | `a+` (append), `w` (overwrite)|
+| `LOG_ROTATION_ENABLED` | **Enable log file rotation** | **`false`** | **`true`, `false`** |
+| `LOG_MAX_SIZE_MB` | Max file size before rotation (MB) | `1` | Any positive integer |
+| `LOG_BACKUP_COUNT` | Number of backup files to keep | `5` | Any non-negative integer |
+
+**Logging Behavior:**
+- **Default**: Logs only to **stdout/stderr** with human-readable text format
+- **File Logging**: When `LOG_TO_FILE=true`, logs to **both** file (JSON format) and console (text format)
+- **Log Rotation**: When `LOG_ROTATION_ENABLED=true`, files rotate at `LOG_MAX_SIZE_MB` with `LOG_BACKUP_COUNT` backup files (e.g., `.log.1`, `.log.2`)
+- **Directory Creation**: Log folder is automatically created if it doesn't exist
+- **Centralized Service**: All modules use the unified `LoggingService` for consistent formatting
+
+**Example Configurations:**
+
+```bash
+# Default: stdout/stderr only (recommended for containers)
+LOG_LEVEL=INFO
+# No additional config needed - logs to stdout/stderr
+
+# Optional: Enable file logging (no rotation)
+LOG_TO_FILE=true
+LOG_FOLDER=/var/log/mcpgateway
+LOG_FILE=gateway.log
+LOG_FILEMODE=a+
+
+# Optional: Enable file logging with rotation
+LOG_TO_FILE=true
+LOG_ROTATION_ENABLED=true
+LOG_MAX_SIZE_MB=10
+LOG_BACKUP_COUNT=3
+LOG_FOLDER=/var/log/mcpgateway
+LOG_FILE=gateway.log
+```
+
+**Default Behavior:**
+- Logs are written **only to stdout/stderr** in human-readable text format
+- File logging is **disabled by default** (no files created)
+- Set `LOG_TO_FILE=true` to enable optional file logging with JSON format
+
+### Observability (OpenTelemetry)
+
+MCP Gateway includes **vendor-agnostic OpenTelemetry support** for distributed tracing. Works with Phoenix, Jaeger, Zipkin, Tempo, DataDog, New Relic, and any OTLP-compatible backend.
+
+| Setting | Description | Default | Options |
+| ------------------------------- | ---------------------------------------------- | --------------------- | ------------------------------------------ |
+| `OTEL_ENABLE_OBSERVABILITY` | Master switch for observability | `true` | `true`, `false` |
+| `OTEL_SERVICE_NAME` | Service identifier in traces | `mcp-gateway` | string |
+| `OTEL_SERVICE_VERSION` | Service version in traces | `0.5.0` | string |
+| `OTEL_DEPLOYMENT_ENVIRONMENT` | Environment tag (dev/staging/prod) | `development` | string |
+| `OTEL_TRACES_EXPORTER` | Trace exporter backend | `otlp` | `otlp`, `jaeger`, `zipkin`, `console`, `none` |
+| `OTEL_RESOURCE_ATTRIBUTES` | Custom resource attributes | (empty) | `key=value,key2=value2` |
+
+**OTLP Configuration** (for Phoenix, Tempo, DataDog, etc.):
+
+| Setting | Description | Default | Options |
+| ------------------------------- | ---------------------------------------------- | --------------------- | ------------------------------------------ |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint | (none) | `http://localhost:4317` |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol | `grpc` | `grpc`, `http/protobuf` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Authentication headers | (empty) | `api-key=secret,x-auth=token` |
+| `OTEL_EXPORTER_OTLP_INSECURE` | Skip TLS verification | `true` | `true`, `false` |
+
+**Alternative Backends** (optional):
+
+| Setting | Description | Default | Options |
+| ------------------------------- | ---------------------------------------------- | --------------------- | ------------------------------------------ |
+| `OTEL_EXPORTER_JAEGER_ENDPOINT` | Jaeger collector endpoint | `http://localhost:14268/api/traces` | URL |
+| `OTEL_EXPORTER_ZIPKIN_ENDPOINT` | Zipkin collector endpoint | `http://localhost:9411/api/v2/spans` | URL |
+
+**Performance Tuning**:
+
+| Setting | Description | Default | Options |
+| ------------------------------- | ---------------------------------------------- | --------------------- | ------------------------------------------ |
+| `OTEL_TRACES_SAMPLER` | Sampling strategy | `parentbased_traceidratio` | `always_on`, `always_off`, `traceidratio` |
+| `OTEL_TRACES_SAMPLER_ARG` | Sample rate (0.0-1.0) | `0.1` | float (0.1 = 10% sampling) |
+| `OTEL_BSP_MAX_QUEUE_SIZE` | Max queued spans | `2048` | int > 0 |
+| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`| Max batch size for export | `512` | int > 0 |
+| `OTEL_BSP_SCHEDULE_DELAY` | Export interval (ms) | `5000` | int > 0 |
+
+**Quick Start with Phoenix**:
+```bash
+# Start Phoenix for LLM observability
+docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest
+
+# Configure gateway
+export OTEL_ENABLE_OBSERVABILITY=true
+export OTEL_TRACES_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+# Run gateway - traces automatically sent to Phoenix
+mcpgateway
+```
+
+> ๐ **What Gets Traced**: Tool invocations, prompt rendering, resource fetching, gateway federation, health checks, plugin execution (if enabled)
+>
+> ๐ **Zero Overhead**: When `OTEL_ENABLE_OBSERVABILITY=false`, all tracing is disabled with no performance impact
+>
+> ๐ **View Traces**: Phoenix UI at `http://localhost:6006`, Jaeger at `http://localhost:16686`, or your configured backend
+
+### Transport
+
+| Setting | Description | Default | Options |
+| ------------------------- | ---------------------------------- | ------- | ------------------------------- |
+| `TRANSPORT_TYPE` | Enabled transports | `all` | `http`,`ws`,`sse`,`stdio`,`all` |
+| `WEBSOCKET_PING_INTERVAL` | WebSocket ping (secs) | `30` | int > 0 |
+| `SSE_RETRY_TIMEOUT` | SSE retry timeout (ms) | `5000` | int > 0 |
+| `SSE_KEEPALIVE_ENABLED` | Enable SSE keepalive events | `true` | bool |
+| `SSE_KEEPALIVE_INTERVAL` | SSE keepalive interval (secs) | `30` | int > 0 |
+| `USE_STATEFUL_SESSIONS` | streamable http config | `false` | bool |
+| `JSON_RESPONSE_ENABLED` | json/sse streams (streamable http) | `true` | bool |
+
+> **๐ก SSE Keepalive Events**: The gateway sends periodic keepalive events to prevent connection timeouts with proxies and load balancers. Disable with `SSE_KEEPALIVE_ENABLED=false` if your client doesn't handle unknown event types. Common intervals: 30s (default), 60s (AWS ALB), 240s (Azure).
+
+### Federation
+
+| Setting | Description | Default | Options |
+| -------------------------- | ---------------------- | ------- | ---------- |
+| `FEDERATION_ENABLED` | Enable federation | `true` | bool |
+| `FEDERATION_DISCOVERY` | Auto-discover peers | `false` | bool |
+| `FEDERATION_PEERS` | Comma-sep peer URLs | `[]` | JSON array |
+| `FEDERATION_TIMEOUT` | Gateway timeout (secs) | `30` | int > 0 |
+| `FEDERATION_SYNC_INTERVAL` | Sync interval (secs) | `300` | int > 0 |
+
+### Resources
+
+| Setting | Description | Default | Options |
+| --------------------- | --------------------- | ---------- | ---------- |
+| `RESOURCE_CACHE_SIZE` | LRU cache size | `1000` | int > 0 |
+| `RESOURCE_CACHE_TTL` | Cache TTL (seconds) | `3600` | int > 0 |
+| `MAX_RESOURCE_SIZE` | Max resource bytes | `10485760` | int > 0 |
+| `ALLOWED_MIME_TYPES` | Acceptable MIME types | see code | JSON array |
+
+### Tools
+
+| Setting | Description | Default | Options |
+| ----------------------- | ------------------------------ | ------- | ------- |
+| `TOOL_TIMEOUT` | Tool invocation timeout (secs) | `60` | int > 0 |
+| `MAX_TOOL_RETRIES` | Max retry attempts | `3` | int โฅ 0 |
+| `TOOL_RATE_LIMIT` | Tool calls per minute | `100` | int > 0 |
+| `TOOL_CONCURRENT_LIMIT` | Concurrent tool invocations | `10` | int > 0 |
+
+### Prompts
+
+| Setting | Description | Default | Options |
+| ----------------------- | -------------------------------- | -------- | ------- |
+| `PROMPT_CACHE_SIZE` | Cached prompt templates | `100` | int > 0 |
+| `MAX_PROMPT_SIZE` | Max prompt template size (bytes) | `102400` | int > 0 |
+| `PROMPT_RENDER_TIMEOUT` | Jinja render timeout (secs) | `10` | int > 0 |
+
+### Health Checks
+
+| Setting | Description | Default | Options |
+| ----------------------- | ----------------------------------------- | ------- | ------- |
+| `HEALTH_CHECK_INTERVAL` | Health poll interval (secs) | `60` | int > 0 |
+| `HEALTH_CHECK_TIMEOUT` | Health request timeout (secs) | `10` | int > 0 |
+| `UNHEALTHY_THRESHOLD` | Fail-count before peer deactivation, | `3` | int > 0 |
+| | Set to -1 if deactivation is not needed. | | |
+
+### Database
+
+| Setting | Description | Default | Options |
+| ----------------------- | ------------------------------- | ------- | ------- |
+| `DB_POOL_SIZE` . | SQLAlchemy connection pool size | `200` | int > 0 |
+| `DB_MAX_OVERFLOW`. | Extra connections beyond pool | `10` | int โฅ 0 |
+| `DB_POOL_TIMEOUT`. | Wait for connection (secs) | `30` | int > 0 |
+| `DB_POOL_RECYCLE`. | Recycle connections (secs) | `3600` | int > 0 |
+| `DB_MAX_RETRIES` . | Max Retry Attempts | `3` | int > 0 |
+| `DB_RETRY_INTERVAL_MS` | Retry Interval (ms) | `2000` | int > 0 |
+
+### Cache Backend
+
+| Setting | Description | Default | Options |
+| ------------------------- | -------------------------- | -------- | ------------------------ |
+| `CACHE_TYPE` | Backend (`memory`/`redis`) | `memory` | `none`, `memory`,`redis` |
+| `REDIS_URL` | Redis connection URL | (none) | string or empty |
+| `CACHE_PREFIX` | Key prefix | `mcpgw:` | string |
+| `REDIS_MAX_RETRIES` | Max Retry Attempts | `3` | int > 0 |
+| `REDIS_RETRY_INTERVAL_MS` | Retry Interval (ms) | `2000` | int > 0 |
+
+> ๐ง `none` disables caching entirely. Use `memory` for dev, `database` for persistence, or `redis` for distributed caching.
+
+### Database Management
+
+MCP Gateway uses Alembic for database migrations. Common commands:
+
+- `make db-current` - Show current database version
+- `make db-upgrade` - Apply pending migrations
+- `make db-migrate` - Create new migration
+- `make db-history` - Show migration history
+- `make db-status` - Detailed migration status
+
+#### Troubleshooting
+
+**Common Issues:**
+
+- **"No 'script_location' key found"**: Ensure you're running from the project root directory.
+
+- **"Unknown SSE event: keepalive" warnings**: Some MCP clients don't recognize keepalive events. These warnings are harmless and don't affect functionality. To disable: `SSE_KEEPALIVE_ENABLED=false`
+
+- **Connection timeouts with proxies/load balancers**: If experiencing timeouts, adjust keepalive interval to match your infrastructure: `SSE_KEEPALIVE_INTERVAL=60` (AWS ALB) or `240` (Azure).
+
+### Development
+
+| Setting | Description | Default | Options |
+| ---------- | ---------------------- | ------- | ------- |
+| `DEV_MODE` | Enable dev mode | `false` | bool |
+| `RELOAD` | Auto-reload on changes | `false` | bool |
+| `DEBUG` | Debug logging | `false` | bool |
+
+
+
+---
+
+## Running
+
+### Makefile
+
+```bash
+ make serve # Run production Gunicorn server on
+ make serve-ssl # Run Gunicorn behind HTTPS on :4444 (uses ./certs)
+```
+
+### Script helper
+
+To run the development (uvicorn) server:
+
+```bash
+make dev
+# or
+./run.sh --reload --log debug --workers 2
+```
+
+> `run.sh` is a wrapper around `uvicorn` that loads `.env`, supports reload, and passes arguments to the server.
+
+Key flags:
+
+| Flag | Purpose | Example |
+| ---------------- | ---------------- | ------------------ |
+| `-e, --env FILE` | load env-file | `--env prod.env` |
+| `-H, --host` | bind address | `--host 127.0.0.1` |
+| `-p, --port` | listen port | `--port 8080` |
+| `-w, --workers` | gunicorn workers | `--workers 4` |
+| `-r, --reload` | auto-reload | `--reload` |
+
+### Manual (Uvicorn)
+
+```bash
+uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4
+```
+
+---
+
+## Authentication examples
+
+```bash
+# Generate a JWT token using JWT_SECRET_KEY and export it as MCPGATEWAY_BEARER_TOKEN
+# Note that the module needs to be installed. If running locally use:
+export MCPGATEWAY_BEARER_TOKEN=$(JWT_SECRET_KEY=my-test-key python3 -m mcpgateway.utils.create_jwt_token)
+
+# Use the JWT token in an API call
+curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools
+```
+
+---
+
+## โ๏ธ AWS / Azure / OpenShift
+
+Deployment details can be found in the GitHub Pages.
+
+## โ๏ธ IBM Cloud Code Engine Deployment
+
+This project supports deployment to [IBM Cloud Code Engine](https://cloud.ibm.com/codeengine) using the **ibmcloud** CLI and the IBM Container Registry.
+
+๐ง Environment Configuration Variables
+ +### Basic + +| Setting | Description | Default | Options | +| --------------- | ---------------------------------------- | ---------------------- | ---------------------- | +| `APP_NAME` | Gateway / OpenAPI title | `MCP Gateway` | string | +| `HOST` | Bind address for the app | `127.0.0.1` | IPv4/IPv6 | +| `PORT` | Port the server listens on | `4444` | 1-65535 | +| `DATABASE_URL` | SQLAlchemy connection URL | `sqlite:///./mcp.db` | any SQLAlchemy dialect | +| `APP_ROOT_PATH` | Subpath prefix for app (e.g. `/gateway`) | (empty) | string | +| `TEMPLATES_DIR` | Path to Jinja2 templates | `mcpgateway/templates` | path | +| `STATIC_DIR` | Path to static files | `mcpgateway/static` | path | + +> ๐ก Use `APP_ROOT_PATH=/foo` if reverse-proxying under a subpath like `https://host.com/foo/`. + +### Authentication + +| Setting | Description | Default | Options | +| --------------------- | ---------------------------------------------------------------- | ------------- | ---------- | +| `BASIC_AUTH_USER` | Username for Admin UI login and HTTP Basic authentication | `admin` | string | +| `BASIC_AUTH_PASSWORD` | Password for Admin UI login and HTTP Basic authentication | `changeme` | string | +| `AUTH_REQUIRED` | Require authentication for all API routes | `true` | bool | +| `JWT_SECRET_KEY` | Secret key used to **sign JWT tokens** for API access | `my-test-key` | string | +| `JWT_ALGORITHM` | Algorithm used to sign the JWTs (`HS256` is default, HMAC-based) | `HS256` | PyJWT algs | +| `TOKEN_EXPIRY` | Expiry of generated JWTs in minutes | `10080` | int > 0 | +| `AUTH_ENCRYPTION_SECRET` | Passphrase used to derive AES key for encrypting tool auth headers | `my-test-salt` | string | + +> ๐ `BASIC_AUTH_USER`/`PASSWORD` are used for: +> +> * Logging into the web-based Admin UI +> * Accessing APIs via Basic Auth (`curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN"`) +> +> ๐ `JWT_SECRET_KEY` is used to: +> +> * Sign JSON Web Tokens (`Authorization: Bearer
+
+
+---
+
+## API Endpoints
+
+You can test the API endpoints through curl, or Swagger UI, and check detailed documentation on ReDoc:
+
+* **Swagger UI** โ [http://localhost:4444/docs](http://localhost:4444/docs)
+* **ReDoc** โ [http://localhost:4444/redoc](http://localhost:4444/redoc)
+
+Generate an API Bearer token, and test the various API endpoints.
+
+โ๏ธ IBM Cloud Code Engine Deployment
+ +### ๐ง Prerequisites + +- Podman **or** Docker installed locally +- IBM Cloud CLI (use `make ibmcloud-cli-install` to install) +- An [IBM Cloud API key](https://cloud.ibm.com/iam/apikeys) with access to Code Engine & Container Registry +- Code Engine and Container Registry services **enabled** in your IBM Cloud account + +--- + +### ๐ฆ Environment Variables + +Create a **`.env`** file (or export the variables in your shell). +The first block is **required**; the second provides **tunable defaults** you can override: + +```bash +# โโ Required โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +IBMCLOUD_REGION=us-south +IBMCLOUD_RESOURCE_GROUP=default +IBMCLOUD_PROJECT=my-codeengine-project +IBMCLOUD_CODE_ENGINE_APP=mcpgateway +IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest +IBMCLOUD_IMG_PROD=mcpgateway/mcpgateway +IBMCLOUD_API_KEY=your_api_key_here # Optional - omit to use interactive `ibmcloud login --sso` + +# โโ Optional overrides (sensible defaults provided) โโโโโโ +IBMCLOUD_CPU=1 # vCPUs for the app +IBMCLOUD_MEMORY=4G # Memory allocation +IBMCLOUD_REGISTRY_SECRET=my-regcred # Name of the Container Registry secret +``` + +> โ **Quick check:** `make ibmcloud-check-env` + +--- + +### ๐ Make Targets + +| Target | Purpose | +| --------------------------- | ------------------------------------------------------------------------- | +| `make ibmcloud-cli-install` | Install IBM Cloud CLI and required plugins | +| `make ibmcloud-login` | Log in to IBM Cloud (API key or SSO) | +| `make ibmcloud-ce-login` | Select the Code Engine project & region | +| `make ibmcloud-tag` | Tag the local container image | +| `make ibmcloud-push` | Push the image to IBM Container Registry | +| `make ibmcloud-deploy` | **Create or update** the Code Engine application (uses CPU/memory/secret) | +| `make ibmcloud-ce-status` | Show current deployment status | +| `make ibmcloud-ce-logs` | Stream logs from the running app | +| `make ibmcloud-ce-rm` | Delete the Code Engine application | + +--- + +### ๐ Example Workflow + +```bash +make ibmcloud-check-env +make ibmcloud-cli-install +make ibmcloud-login +make ibmcloud-ce-login +make ibmcloud-tag +make ibmcloud-push +make ibmcloud-deploy +make ibmcloud-ce-status +make ibmcloud-ce-logs +``` + +
+
+
+---
+
+๐ Authentication & Health Checks
+ +```bash +# Generate a bearer token using the configured secret key (use the same as your .env) +export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token -u admin --secret my-test-key) +echo ${MCPGATEWAY_BEARER_TOKEN} + +# Quickly confirm that authentication works and the gateway is healthy +curl -s -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/health +# {"status":"healthy"} + +# Quickly confirm the gateway version & DB connectivity +curl -s -k -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" https://localhost:4444/version | jq +``` + +
+
+
+---
+
+๐งฑ Protocol APIs (MCP) /protocol
+ +```bash +# Initialize MCP session +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "protocol_version":"2025-03-26", + "capabilities":{}, + "client_info":{"name":"MyClient","version":"1.0.0"} + }' \ + http://localhost:4444/protocol/initialize + +# Ping (JSON-RPC style) +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \ + http://localhost:4444/protocol/ping + +# Completion for prompt/resource arguments (not implemented) +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "ref":{"type":"ref/prompt","name":"example_prompt"}, + "argument":{"name":"topic","value":"py"} + }' \ + http://localhost:4444/protocol/completion/complete + +# Sampling (streaming) (not implemented) +curl -N -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "messages":[{"role":"user","content":{"type":"text","text":"Hello"}}], + "maxTokens":16 + }' \ + http://localhost:4444/protocol/sampling/createMessage +``` + +
+
+
+---
+
+๐ง JSON-RPC Utility /rpc
+ +```bash +# Generic JSON-RPC calls (tools, gateways, roots, etc.) +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"list_tools"}' \ + http://localhost:4444/rpc +``` + +Handles any method name: `list_tools`, `list_gateways`, `prompts/get`, or invokes a tool if method matches a registered tool name . + +
+
+
+---
+
+๐ง Tool Management /tools
+ + +```bash +# Register a new tool +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name":"clock_tool", + "url":"http://localhost:9000/rpc", + "description":"Returns current time", + "input_schema":{ + "type":"object", + "properties":{"timezone":{"type":"string"}}, + "required":[] + } + }' \ + http://localhost:4444/tools + +# List tools +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools + +# Get tool by ID +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools/1 + +# Update tool +curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ "description":"Updated desc" }' \ + http://localhost:4444/tools/1 + +# Toggle active status +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/tools/1/toggle?activate=false +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/tools/1/toggle?activate=true + +# Delete tool +curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools/1 +``` + +
+
+
+---
+
+๐ Gateway Management /gateways
+ +```bash +# Register an MCP server as a new gateway provider +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"peer_gateway","url":"http://peer:4444"}' \ + http://localhost:4444/gateways + +# List gateways +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/gateways + +# Get gateway by ID +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/gateways/1 + +# Update gateway +curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"description":"New description"}' \ + http://localhost:4444/gateways/1 + +# Toggle active status +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/gateways/1/toggle?activate=false + +# Delete gateway +curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/gateways/1 +``` + +
+
+
+---
+
+๐ Resource Management /resources
+ + +```bash +# Register resource +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "uri":"config://app/settings", + "name":"App Settings", + "content":"key=value" + }' \ + http://localhost:4444/resources + +# List resources +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/resources + +# Read a resource +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/resources/config://app/settings + +# Update resource +curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"content":"new=value"}' \ + http://localhost:4444/resources/config://app/settings + +# Delete resource +curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/resources/config://app/settings + +# Subscribe to updates (SSE) +curl -N -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/resources/subscribe/config://app/settings +``` + +
+
+
+---
+
+๐ Prompt Management /prompts
+ +```bash +# Create prompt template +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name":"greet", + "template":"Hello, {{ user }}!", + "argument_schema":{ + "type":"object", + "properties":{"user":{"type":"string"}}, + "required":["user"] + } + }' \ + http://localhost:4444/prompts + +# List prompts +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/prompts + +# Get prompt (with args) +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"user":"Alice"}' \ + http://localhost:4444/prompts/greet + +# Get prompt (no args) +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/prompts/greet + +# Update prompt +curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"template":"Hi, {{ user }}!"}' \ + http://localhost:4444/prompts/greet + +# Toggle active +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/prompts/5/toggle?activate=false + +# Delete prompt +curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/prompts/greet +``` + +
+
+
+---
+
+๐ฒ Root Management /roots
+ +```bash +# List roots +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/roots + +# Add root +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"uri":"/data","name":"Data Root"}' \ + http://localhost:4444/roots + +# Remove root +curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/roots/%2Fdata + +# Subscribe to root changes (SSE) +curl -N -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/roots/changes +``` + +
+
+
+---
+
+๐ฅ๏ธ Server Management /servers
+ +```bash +# List servers +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers + +# Get server +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers/UUID_OF_SERVER_1 + +# Create server +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"db","description":"Database","associatedTools": ["1","2","3"]}' \ + http://localhost:4444/servers + +# Update server +curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"description":"Updated"}' \ + http://localhost:4444/servers/UUID_OF_SERVER_1 + +# Toggle active +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ + http://localhost:4444/servers/UUID_OF_SERVER_1/toggle?activate=false +``` + +
+
+
+---
+
+๐ Metrics /metrics
+ +```bash +# Get aggregated metrics +curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/metrics + +# Reset metrics (all or per-entity) +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/metrics/reset +curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/metrics/reset?entity=tool&id=1 +``` + +
+
+
+---
+
+๐ก Events & Health
+ +```bash +# SSE: all events +curl -N -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/events + +# WebSocket +wscat -c ws://localhost:4444/ws \ + -H "Authorization: Basic $(echo -n admin:changeme|base64)" + +# Health check +curl http://localhost:4444/health +``` + +Full Swagger UI at `/docs`. + +
+
+
+---
+
+## Testing
+
+```bash
+make test # Run unit tests
+make lint # Run lint tools
+```
+
+## Doctest Coverage
+
+MCP Context Forge implements comprehensive doctest coverage to ensure all code examples in documentation are tested and verified:
+
+```bash
+make doctest # Run all doctests
+make doctest-verbose # Run with detailed output
+make doctest-coverage # Generate coverage report
+make doctest-check # Check coverage percentage
+```
+
+**Coverage Status:**
+- โ
**Transport Modules**: 100% (base, stdio, SSE, WebSocket, streamable HTTP)
+- โ
**Utility Functions**: 100% (slug generation, JWT tokens, validation)
+- โ
**Configuration**: 100% (settings, environment variables)
+- ๐ **Service Classes**: ~60% (in progress)
+- ๐ **Complex Classes**: ~40% (in progress)
+
+**Benefits:**
+- All documented examples are automatically tested
+- Documentation stays accurate and up-to-date
+- Developers can run examples directly from docstrings
+- Regression prevention through automated verification
+
+For detailed information, see the [Doctest Coverage Guide](https://ibm.github.io/mcp-context-forge/development/doctest-coverage/).
+
+---
+
+## Project Structure
+
+๐ ๏ธ Sample Tool
+ +```bash +uvicorn sample_tool.clock_tool:app --host 0.0.0.0 --port 9000 +``` + +```bash +curl -X POST -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"get_time","params":{"timezone":"UTC"}}' \ + http://localhost:9000/rpc +``` + +
+
+
+---
+
+## API Documentation
+
+* **Swagger UI** โ [http://localhost:4444/docs](http://localhost:4444/docs)
+* **ReDoc** โ [http://localhost:4444/redoc](http://localhost:4444/redoc)
+* **Admin Panel** โ [http://localhost:4444/admin](http://localhost:4444/admin)
+
+---
+
+## Makefile targets
+
+This project offer the following Makefile targets. Type `make` in the project root to show all targets.
+
+๐ Directory and file structure for mcpgateway
+ +```bash +# โโโโโโโโโโ CI / Quality & Meta-files โโโโโโโโโโ +โโโ .bumpversion.cfg # Automated semantic-version bumps +โโโ .coveragerc # Coverage.py settings +โโโ .darglint # Doc-string linter rules +โโโ .dockerignore # Context exclusions for image builds +โโโ .editorconfig # Consistent IDE / editor behaviour +โโโ .env # Local runtime variables (git-ignored) +โโโ .env.ce # IBM Code Engine runtime env (ignored) +โโโ .env.ce.example # Sample env for IBM Code Engine +โโโ .env.example # Generic sample env file +โโโ .env.gcr # Google Cloud Run runtime env (ignored) +โโโ .eslintrc.json # ESLint rules for JS / TS assets +โโโ .flake8 # Flake-8 configuration +โโโ .gitattributes # Git attributes (e.g. EOL normalisation) +โโโ .github # GitHub settings, CI/CD workflows & templates +โ โโโ CODEOWNERS # Default reviewers +โ โโโ workflows/ # Bandit, Docker, CodeQL, Python Package, Container Deployment, etc. +โโโ .gitignore # Git exclusion rules +โโโ .hadolint.yaml # Hadolint rules for Dockerfiles +โโโ .htmlhintrc # HTMLHint rules +โโโ .markdownlint.json # Markdown-lint rules +โโโ .pre-commit-config.yaml # Pre-commit hooks (ruff, black, mypy, ...) +โโโ .pycodestyle # PEP-8 checker settings +โโโ .pylintrc # Pylint configuration +โโโ .pyspelling.yml # Spell-checker dictionary & filters +โโโ .ruff.toml # Ruff linter / formatter settings +โโโ .spellcheck-en.txt # Extra dictionary entries +โโโ .stylelintrc.json # Stylelint rules for CSS +โโโ .travis.yml # Legacy Travis CI config (reference) +โโโ .whitesource # WhiteSource security-scanning config +โโโ .yamllint # yamllint ruleset + +# โโโโโโโโโโ Documentation & Guidance โโโโโโโโโโ +โโโ CHANGELOG.md # Version-by-version change log +โโโ CODE_OF_CONDUCT.md # Community behaviour guidelines +โโโ CONTRIBUTING.md # How to file issues & send PRs +โโโ DEVELOPING.md # Contributor workflows & style guide +โโโ LICENSE # Apache License 2.0 +โโโ README.md # Project overview & quick-start +โโโ SECURITY.md # Security policy & CVE disclosure process +โโโ TESTING.md # Testing strategy, fixtures & guidelines + +# โโโโโโโโโโ Containerisation & Runtime โโโโโโโโโโ +โโโ Containerfile # OCI image build (Docker / Podman) +โโโ Containerfile.lite # FROM scratch UBI-Micro production build +โโโ docker-compose.yml # Local multi-service stack +โโโ podman-compose-sonarqube.yaml # One-liner SonarQube stack +โโโ run-gunicorn.sh # Opinionated Gunicorn startup script +โโโ run.sh # Uvicorn shortcut with arg parsing + +# โโโโโโโโโโ Build / Packaging / Tooling โโโโโโโโโโ +โโโ MANIFEST.in # sdist inclusion rules +โโโ Makefile # Dev & deployment targets +โโโ package-lock.json # Deterministic npm lock-file +โโโ package.json # Front-end / docs tooling deps +โโโ pyproject.toml # Poetry / PDM config & lint rules +โโโ sonar-code.properties # SonarQube analysis settings +โโโ uv.lock # UV resolver lock-file + +# โโโโโโโโโโ Kubernetes & Helm Assets โโโโโโโโโโ +โโโ charts # Helm chart(s) for K8s / OpenShift +โ โโโ mcp-stack # Umbrella chart +โ โ โโโ Chart.yaml # Chart metadata +โ โ โโโ templates/... # Manifest templates +โ โ โโโ values.yaml # Default values +โ โโโ README.md # Install / upgrade guide +โโโ k8s # Raw (non-Helm) K8s manifests +โ โโโ *.yaml # Deployment, Service, PVC resources + +# โโโโโโโโโโ Documentation Source โโโโโโโโโโ +โโโ docs # MkDocs site source +โ โโโ base.yml # MkDocs "base" configuration snippet (do not modify) +โ โโโ mkdocs.yml # Site configuration (requires base.yml) +โ โโโ requirements.txt # Python dependencies for the MkDocs site +โ โโโ Makefile # Make targets for building/serving the docs +โ โโโ theme # Custom MkDocs theme assets +โ โโโ logo.png # Logo for the documentation theme +โ โโโ docs # Markdown documentation +โ โโโ architecture/ # ADRs for the project +โ โโโ articles/ # Long-form writeups +โ โโโ blog/ # Blog posts +โ โโโ deployment/ # Deployment guides (AWS, Azure, etc.) +โ โโโ development/ # Development workflows & CI docs +โ โโโ images/ # Diagrams & screenshots +โ โโโ index.md # Top-level docs landing page +โ โโโ manage/ # Management topics (backup, logging, tuning, upgrade) +โ โโโ overview/ # Feature overviews & UI documentation +โ โโโ security/ # Security guidance & policies +โ โโโ testing/ # Testing strategy & fixtures +โ โโโ using/ # User-facing usage guides (agents, clients, etc.) +โ โโโ media/ # Social media, press coverage, videos & testimonials +โ โ โโโ press/ # Press articles and blog posts +โ โ โโโ social/ # Tweets, LinkedIn posts, YouTube embeds +โ โ โโโ testimonials/ # Customer quotes & community feedback +โ โ โโโ kit/ # Media kit & logos for bloggers & press +โโโ dictionary.dic # Custom dictionary for spell-checker (make spellcheck) + +# โโโโโโโโโโ Application & Libraries โโโโโโโโโโ +โโโ agent_runtimes # Configurable agentic frameworks converted to MCP Servers +โโโ mcpgateway # โ main application package +โ โโโ __init__.py # Package metadata & version constant +โ โโโ admin.py # FastAPI routers for Admin UI +โ โโโ cache +โ โ โโโ __init__.py +โ โ โโโ resource_cache.py # LRU+TTL cache implementation +โ โ โโโ session_registry.py # Session โ cache mapping +โ โโโ config.py # Pydantic settings loader +โ โโโ db.py # SQLAlchemy models & engine setup +โ โโโ federation +โ โ โโโ __init__.py +โ โ โโโ discovery.py # Peer-gateway discovery +โ โ โโโ forward.py # RPC forwarding +โ โโโ handlers +โ โ โโโ __init__.py +โ โ โโโ sampling.py # Streaming sampling handler +โ โโโ main.py # FastAPI app factory & startup events +โ โโโ mcp.db # SQLite fixture for tests +โ โโโ py.typed # PEP 561 marker (ships type hints) +โ โโโ schemas.py # Shared Pydantic DTOs +โ โโโ services +โ โ โโโ __init__.py +โ โ โโโ completion_service.py # Prompt / argument completion +โ โ โโโ gateway_service.py # Peer-gateway registry +โ โ โโโ logging_service.py # Central logging helpers +โ โ โโโ prompt_service.py # Prompt CRUD & rendering +โ โ โโโ resource_service.py # Resource registration & retrieval +โ โ โโโ root_service.py # File-system root registry +โ โ โโโ server_service.py # Server registry & monitoring +โ โ โโโ tool_service.py # Tool registry & invocation +โ โโโ static +โ โ โโโ admin.css # Styles for Admin UI +โ โ โโโ admin.js # Behaviour for Admin UI +โ โโโ templates +โ โ โโโ admin.html # HTMX/Alpine Admin UI template +โ โโโ transports +โ โ โโโ __init__.py +โ โ โโโ base.py # Abstract transport interface +โ โ โโโ sse_transport.py # Server-Sent Events transport +โ โ โโโ stdio_transport.py # stdio transport for embedding +โ โ โโโ websocket_transport.py # WS transport with ping/pong +โ โโโ models.py # Core enums / type aliases +โ โโโ utils +โ โ โโโ create_jwt_token.py # CLI & library for JWT generation +โ โ โโโ services_auth.py # Service-to-service auth dependency +โ โ โโโ verify_credentials.py # Basic / JWT auth helpers +โ โโโ validation +โ โ โโโ __init__.py +โ โ โโโ jsonrpc.py # JSON-RPC 2.0 validation +โ โโโ version.py # Library version helper +โโโ mcpgateway-wrapper # Stdio client wrapper (PyPI) +โ โโโ pyproject.toml +โ โโโ README.md +โ โโโ src/mcpgateway_wrapper/ +โ โโโ __init__.py +โ โโโ server.py # Wrapper entry-point +โโโ mcp-servers # Sample downstream MCP servers +โโโ mcp.db # Default SQLite DB (auto-created) +โโโ mcpgrid # Experimental grid client / PoC +โโโ os_deps.sh # Installs system-level deps for CI + +# โโโโโโโโโโ Tests & QA Assets โโโโโโโโโโ +โโโ test_readme.py # Guard: README stays in sync +โโโ tests +โ โโโ conftest.py # Shared fixtures +โ โโโ e2e/... # End-to-end scenarios +โ โโโ hey/... # Load-test logs & helper script +โ โโโ integration/... # API-level integration tests +โ โโโ unit/... # Pure unit tests for business logic +``` + +
+.tgz
+helm-deploy - Upgrade/Install chart into Minikube (profile mcpgw)
+helm-delete - Uninstall the chart release from Minikube
+๐ LOCAL PYPI SERVER
+local-pypi-install - Install pypiserver for local testing
+local-pypi-start - Start local PyPI server on :8084 (no auth)
+local-pypi-start-auth - Start local PyPI server with basic auth (admin/admin)
+local-pypi-stop - Stop local PyPI server
+local-pypi-upload - Upload existing package to local PyPI (no auth)
+local-pypi-upload-auth - Upload existing package to local PyPI (with auth)
+local-pypi-test - Install package from local PyPI
+local-pypi-clean - Full cycle: build โ upload โ install locally
+๐ LOCAL DEVPI SERVER
+devpi-install - Install devpi server and client
+devpi-init - Initialize devpi server (first time only)
+devpi-start - Start devpi server
+devpi-stop - Stop devpi server
+devpi-setup-user - Create user and dev index
+devpi-upload - Upload existing package to devpi
+devpi-test - Install package from devpi
+devpi-clean - Full cycle: build โ upload โ install locally
+devpi-status - Show devpi server status
+devpi-web - Open devpi web interface
+```
+
+
+## ๐ Troubleshooting
+
+๐ง Available Makefile targets
+ +```bash +๐ MCP CONTEXT FORGE (An enterprise-ready Model Context Protocol Gateway) +๐ง SYSTEM-LEVEL DEPENDENCIES (DEV BUILD ONLY) +os-deps - Install Graphviz, Pandoc, Trivy, SCC used for dev docs generation and security scan +๐ฑ VIRTUAL ENVIRONMENT & INSTALLATION +venv - Create a fresh virtual environment with uv & friends +activate - Activate the virtual environment in the current shell +install - Install project into the venv +install-dev - Install project (incl. dev deps) into the venv +install-db - Install project (incl. postgres and redis) into venv +update - Update all installed deps inside the venv +check-env - Verify all required env vars in .env are present +โถ๏ธ SERVE & TESTING +serve - Run production Gunicorn server on :4444 +certs - Generate self-signed TLS cert & key in ./certs (won't overwrite) +serve-ssl - Run Gunicorn behind HTTPS on :4444 (uses ./certs) +dev - Run fast-reload dev server (uvicorn) +run - Execute helper script ./run.sh +test - Run unit tests with pytest +test-curl - Smoke-test API endpoints with curl script +pytest-examples - Run README / examples through pytest-examples +clean - Remove caches, build artefacts, virtualenv, docs, certs, coverage, SBOM, etc. +๐ COVERAGE & METRICS +coverage - Run tests with coverage, emit md/HTML/XML + badge +pip-licenses - Produce dependency license inventory (markdown) +scc - Quick LoC/complexity snapshot with scc +scc-report - Generate HTML LoC & per-file metrics with scc +๐ DOCUMENTATION & SBOM +docs - Build docs (graphviz + handsdown + images + SBOM) +images - Generate architecture & dependency diagrams +๐ LINTING & STATIC ANALYSIS +lint - Run the full linting suite (see targets below) +black - Reformat code with black +autoflake - Remove unused imports / variables with autoflake +isort - Organise & sort imports with isort +flake8 - PEP-8 style & logical errors +pylint - Pylint static analysis +markdownlint - Lint Markdown files with markdownlint (requires markdownlint-cli) +mypy - Static type-checking with mypy +bandit - Security scan with bandit +pydocstyle - Docstring style checker +pycodestyle - Simple PEP-8 checker +pre-commit - Run all configured pre-commit hooks +ruff - Ruff linter + formatter +ty - Ty type checker from astral +pyright - Static type-checking with Pyright +radon - Code complexity & maintainability metrics +pyroma - Validate packaging metadata +importchecker - Detect orphaned imports +spellcheck - Spell-check the codebase +fawltydeps - Detect undeclared / unused deps +wily - Maintainability report +pyre - Static analysis with Facebook Pyre +depend - List dependencies in โrequirements format +snakeviz - Profile & visualise with snakeviz +pstats - Generate PNG call-graph from cProfile stats +spellcheck-sort - Sort local spellcheck dictionary +tox - Run tox across multi-Python versions +sbom - Produce a CycloneDX SBOM and vulnerability scan +pytype - Flow-sensitive type checker +check-manifest - Verify sdist/wheel completeness +yamllint - Lint YAML files (uses .yamllint) +jsonlint - Validate every *.json file with jq (--exit-status) +tomllint - Validate *.toml files with tomlcheck +๐ธ๏ธ WEBPAGE LINTERS & STATIC ANALYSIS (HTML/CSS/JS lint + security scans + formatting) +install-web-linters - Install HTMLHint, Stylelint, ESLint, Retire.js & Prettier via npm +lint-web - Run HTMLHint, Stylelint, ESLint, Retire.js and npm audit +format-web - Format HTML, CSS & JS files with Prettier +osv-install - Install/upgrade osv-scanner (Go) +osv-scan-source - Scan source & lockfiles for CVEs +osv-scan-image - Scan the built container image for CVEs +osv-scan - Run all osv-scanner checks (source, image, licence) +๐ก SONARQUBE ANALYSIS +sonar-deps-podman - Install podman-compose + supporting tools +sonar-deps-docker - Install docker-compose + supporting tools +sonar-up-podman - Launch SonarQube with podman-compose +sonar-up-docker - Launch SonarQube with docker-compose +sonar-submit-docker - Run containerized Sonar Scanner CLI with Docker +sonar-submit-podman - Run containerized Sonar Scanner CLI with Podman +pysonar-scanner - Run scan with Python wrapper (pysonar-scanner) +sonar-info - How to create a token & which env vars to export +๐ก๏ธ SECURITY & PACKAGE SCANNING +trivy - Scan container image for CVEs (HIGH/CRIT). Needs podman socket enabled +grype-scan - Scan container for security audit and vulnerability scanning +dockle - Lint the built container image via tarball (no daemon/socket needed) +hadolint - Lint Containerfile/Dockerfile(s) with hadolint +pip-audit - Audit Python dependencies for published CVEs +๐ฆ DEPENDENCY MANAGEMENT +deps-update - Run update-deps.py to update all dependencies in pyproject.toml and docs/requirements.txt +containerfile-update - Update base image in Containerfile to latest tag +๐ฆ PACKAGING & PUBLISHING +dist - Clean-build wheel *and* sdist into ./dist +wheel - Build wheel only +sdist - Build source distribution only +verify - Build + twine + check-manifest + pyroma (no upload) +publish - Verify, then upload to PyPI (needs TWINE_* creds) +๐ฆญ PODMAN CONTAINER BUILD & RUN +podman-dev - Build development container image +podman - Build container image +podman-prod - Build production container image (using ubi-micro โ scratch). Not supported on macOS. +podman-run - Run the container on HTTP (port 4444) +podman-run-shell - Run the container on HTTP (port 4444) and start a shell +podman-run-ssl - Run the container on HTTPS (port 4444, self-signed) +podman-run-ssl-host - Run the container on HTTPS with --network=host (port 4444, self-signed) +podman-stop - Stop & remove the container +podman-test - Quick curl smoke-test against the container +podman-logs - Follow container logs (โC to quit) +podman-stats - Show container resource stats (if supported) +podman-top - Show live top-level process info in container +podman-shell - Open an interactive shell inside the Podman container +๐ DOCKER BUILD & RUN +docker-dev - Build development Docker image +docker - Build production Docker image +docker-prod - Build production container image (using ubi-micro โ scratch). Not supported on macOS. +docker-run - Run the container on HTTP (port 4444) +docker-run-ssl - Run the container on HTTPS (port 4444, self-signed) +docker-stop - Stop & remove the container +docker-test - Quick curl smoke-test against the container +docker-logs - Follow container logs (โC to quit) +docker-stats - Show container resource usage stats (non-streaming) +docker-top - Show top-level process info in Docker container +docker-shell - Open an interactive shell inside the Docker container +๐ ๏ธ COMPOSE STACK - Build / start / stop the multi-service stack +compose-up - Bring the whole stack up (detached) +compose-restart - Recreate changed containers, pulling / building as needed +compose-build - Build (or rebuild) images defined in the compose file +compose-pull - Pull the latest images only +compose-logs - Tail logs from all services (Ctrl-C to exit) +compose-ps - Show container status table +compose-shell - Open an interactive shell in the "gateway" container +compose-stop - Gracefully stop the stack (keep containers) +compose-down - Stop & remove containers (keep named volumes) +compose-rm - Remove *stopped* containers +compose-clean - โจ Down **and** delete named volumes (data-loss โ ) +โ๏ธ IBM CLOUD CODE ENGINE +ibmcloud-check-env - Verify all required IBM Cloud env vars are set +ibmcloud-cli-install - Auto-install IBM Cloud CLI + required plugins (OS auto-detected) +ibmcloud-login - Login to IBM Cloud CLI using IBMCLOUD_API_KEY (--sso) +ibmcloud-ce-login - Set Code Engine target project and region +ibmcloud-list-containers - List deployed Code Engine apps +ibmcloud-tag - Tag container image for IBM Container Registry +ibmcloud-push - Push image to IBM Container Registry +ibmcloud-deploy - Deploy (or update) container image in Code Engine +ibmcloud-ce-logs - Stream logs for the deployed application +ibmcloud-ce-status - Get deployment status +ibmcloud-ce-rm - Delete the Code Engine application +๐งช MINIKUBE LOCAL CLUSTER +minikube-install - Install Minikube (macOS, Linux, or Windows via choco) +helm-install - Install Helm CLI (macOS, Linux, or Windows) +minikube-start - Start local Minikube cluster with Ingress + DNS + metrics-server +minikube-stop - Stop the Minikube cluster +minikube-delete - Delete the Minikube cluster +minikube-image-load - Build and load ghcr.io/ibm/mcp-context-forge:latest into Minikube +minikube-k8s-apply - Apply Kubernetes manifests from deployment/k8s/ +minikube-status - Show status of Minikube and ingress pods +๐ ๏ธ HELM CHART TASKS +helm-lint - Lint the Helm chart (static analysis) +helm-package - Package the chart into dist/ as mcp-stack-
+
+
+Port publishing on WSL2 (rootless Podman & Docker Desktop)
+ +### Diagnose the listener + +```bash +# Inside your WSL distro +ss -tlnp | grep 4444 # Use ss +netstat -anp | grep 4444 # or netstat +``` + +*Seeing `:::4444 LISTEN rootlessport` is normal* - the IPv6 wildcard +socket (`::`) also accepts IPv4 traffic **when** +`net.ipv6.bindv6only = 0` (default on Linux). + +### Why localhost fails on Windows + +WSL 2's NAT layer rewrites only the *IPv6* side of the dual-stack listener. From Windows, `http://127.0.0.1:4444` (or Docker Desktop's "localhost") therefore times-out. + +#### Fix (Podman rootless) + +```bash +# Inside the WSL distro +echo "wsl" | sudo tee /etc/containers/podman-machine +systemctl --user restart podman.socket +``` + +`ss` should now show `0.0.0.0:4444` instead of `:::4444`, and the +service becomes reachable from Windows *and* the LAN. + +#### Fix (Docker Desktop > 4.19) + +Docker Desktop adds a "WSL integration" switch per-distro. +Turn it **on** for your distro, restart Docker Desktop, then restart the +container: + +```bash +docker restart mcpgateway +``` + +
+
+
+## Contributing
+
+1. Fork the repo, create a feature branch.
+2. Run `make lint` and fix any issues.
+3. Keep `make test` green and 100% coverage.
+4. Open a PR - describe your changes clearly.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+---
+
+## Changelog
+
+A complete changelog can be found here: [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+Licensed under the **Apache License 2.0** - see [LICENSE](./LICENSE)
+
+
+## Core Authors and Maintainers
+
+- [Mihai Criveti](https://www.linkedin.com/in/crivetimihai) - Distinguished Engineer, Agentic AI
+
+Special thanks to our contributors for helping us improve ContextForge MCP Gateway:
+
+
+