Merge pull request #66 from IBM/full-doc-review

Full doc review, JWT auth for examples and make the CLI listen on 127.0.0.1

Author: crivetimihai

.github/.renovate.json5

@@ -4,9 +4,10 @@
    * 1️⃣  General bot behaviour
    * ──────────────────────────
    */
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
     "config:base",       /* sensible defaults, but no major-bumps or grouping magic */
-    ":weekly"            /* run once a week, early Monday UTC (≈ Sun night US / Mon AM EU) */
+    "schedule:daily"     /* run once a day */
   ],
 
   /* Only open one brand-new branch or PR during the weekly window */

DEVELOPING.md

@@ -3,8 +3,7 @@
 ```
 export MCP_GATEWAY_BASE_URL=http://localhost:4444
 export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1
-export MCP_AUTH_USER=admin
-export MCP_AUTH_PASS=changeme
+export MCP_AUTH_TOKEN="your_bearer_token"
 
 
 npx @modelcontextprotocol/inspector # SSE

README.md

@@ -56,25 +56,77 @@ MCP Gateway is [published on PyPi](https://pypi.org/project/mcp-contextforge-gat
 
 ```bash
 # Create a virtual environment and activate it
+mkdir mcpgateway && cd mcpgateway # directory to store Python venv and mcp.db
 python3 -m venv .venv
 . ./.venv/bin/activate
 
 # Install mcp-contextforge-gateway
 pip install mcp-contextforge-gateway
 
-# Run mcpgateway with default options, listening on port 4444
-mcpgateway
+# Run mcpgateway with default options (binds to 127.0.0.1:4444) with admin:changeme
+mcpgateway  # login to http://127.0.0.1:4444
 
-# Optional: configure env, and login with admin:password at http://127.0.0.1:9999/admin
-BASIC_AUTH_PASSWORD=password mcpgateway --host 127.0.0.1 --port 9999
+# Optional: run in background with configured password/key and listen to all IPs
+BASIC_AUTH_PASSWORD=password JWT_SECRET_KEY=my-test-key mcpgateway --host 0.0.0.0 --port 4444 & bg
 
 # List all options
 mcpgateway --help
+
+# Generate your JWT token from the key
+export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
+
+# Run a local MCP Server (github) listening on SSE http://localhost:8000/sse
+pip install uvenv
+npx -y supergateway --stdio "uvenv run mcp-server-git"
+
+#--------------------------------------------
+# Register the MCP Server with the gateway and test it
+# The curl steps can also from the admin ui: http://localhost:4444/admin
+# For more info on the API see /docs and /redoc *after* login to /admin
+#---------------------------------------------
+# Test the API (assume you have curl and jq installed)
+curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/version | jq
+
+# Register the MCP server as a new gateway provider
+curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"github_mcp_server","url":"http://localhost:8000/sse"}' \
+     http://localhost:4444/gateways
+
+# List gateways - you should see [{"id":1,"name":"github_mcp_server","url":"http://localhost:8000/sse" ...
+curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/gateways | jq
+
+# Get gateway by ID
+curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/gateways/1
+
+# List the global tools
+curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq
+
+# Create a virtual server with tool 1,2,3 form global tools catalog
+# You can configure virtual servers with multiple tools/resources/prompts from registered MCP server (gateways)
+curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"devtools_mcp_server","description":"My developer tools","associatedTools": ["1","2","3"]}' \
+     http://localhost:4444/servers
+
+# List servers
+curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers
+
+# Get an individual server
+curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers/1
+
+# You can now use http://localhost:4444/servers/1 as an SSE server with the configured JWT token in any MCP client
+
+# To stop the running process, you can either:
+fg # Return the process to foreground, you can not Ctrl + C, or:
+pkill mcpgateway
 ```
 
-## Quick Start (Pre-built Image)
+See [.env.example](.env.example) for full list of ENV variables you can use to override the configuration.
 
-If you just want to run the gateway using the official image from GitHub Container Registry:
+## Quick Start (Pre-built Container Image)
+
+If you just want to run the gateway using the official OCI container image from GitHub Container Registry:
 
 ```bash
 docker run -d --name mcpgateway \
@@ -93,6 +145,8 @@ docker logs mcpgateway
 You can now access the UI at [http://localhost:4444/admin](http://localhost:4444/admin)
 
 > 💡 You can also use `--env-file .env` if you have a config file already. See the provided [.env.example](.env.example)
+> 💡 To access local tools, consider using `--network=host`
+> 💡 Consider using a stable / release version of the image, ex: `ghcr.io/ibm/mcp-context-forge:v0.1.0`
 
 ### Optional: Mount a local volume for persistent SQLite storage
 
@@ -120,7 +174,7 @@ curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
 
 ### Running the mcpgateway-wrapper
 
-The mcpgateway-wrapper lets you connect to the gateway over stdio.
+The mcpgateway-wrapper lets you connect to the gateway over stdio, while retaining authentication using the JWT token when the wrapper connect to a remote gateway. You should run this from a MCP client. You can test this from a shell with:
 
 ```bash
 docker run -i --name mcpgateway-wrapper \
@@ -130,10 +184,15 @@ docker run -i --name mcpgateway-wrapper \
   -e MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN \
   ghcr.io/ibm/mcp-context-forge:latest \
   run --directory mcpgateway-wrapper mcpgateway-wrapper
+# You'll see a message similar to: Installed 21 packages in 6ms - it's now expecting input from an MCP client
 ```
 
 ### Running from a MCP Client
 
+The `mcpgateway-wrapper` should be used with an MCP Client that does not support SSE. You can configure it as such.
+
+Remember to replace the `MCP_SERVER_CATALOG_URL` with the actual URL of your MCP Gateway. Consider container networking - when running this via a container engine, this should represent a network accessible from Docker/Podman, ex: `http://host.docker.internal:4444/servers/1`
+
 ```json
 {
   "servers": {
@@ -142,9 +201,10 @@ docker run -i --name mcpgateway-wrapper \
       "args": [
         "run",
         "--rm",
+        "--network=host",
         "-i",
         "-e",
-        "MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444/servers/1",
+        "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1",
         "-e",
         "MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}",
         "--entrypoint",
@@ -162,14 +222,53 @@ docker run -i --name mcpgateway-wrapper \
   }
 }
 ```
+
+## Quick Start (Claude Desktop)
+
+To add the mcpgateway to Claude Desktop (or similar MCP Clients) go to `File > Settings > Developer > Edit Config` and add:
+
+```json
+{
+  "mcpServers": {
+    "mcpgateway-wrapper": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "--network=host",
+        "-i",
+        "-e",
+        "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/1",
+        "-e",
+        "MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}",
+        "--entrypoint",
+        "uv",
+        "ghcr.io/ibm/mcp-context-forge:latest",
+        "run",
+        "--directory",
+        "mcpgateway-wrapper",
+        "mcpgateway-wrapper"
+      ],
+      "env": {
+        "MCPGATEWAY_BEARER_TOKEN": "<place your token here>"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop (exiting from system tray). Go back to `File > Settings > Developer > Edit Config` to check on your configuration and view the logs.
+
+For more details, see the [Claude MCP quickstart](https://modelcontextprotocol.io/quickstart/server). For issues, see [MCP Debugging](https://modelcontextprotocol.io/docs/tools/debugging).
+
 ---
 
 ## Quick Start (manual install)
 
 ### Prerequisites
 
 * **Python ≥ 3.10**
-* **GNU Make** (all common workflows are Make targets)
+* **GNU Make** (optional, but all common workflows are available as Make targets)
 * Optional: **Docker / Podman** for containerised runs
 
 ### One-liner (dev)
@@ -260,6 +359,8 @@ docker run --name mcp-postgres \
   -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)
@@ -563,6 +664,7 @@ 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
@@ -812,7 +914,7 @@ curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/s
 # Create server
 curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
-     -d '{"name":"db","description":"Database"}' \
+     -d '{"name":"db","description":"Database","associatedTools": ["1","2","3"]}' \
      http://localhost:4444/servers
 
 # Update server

docs/docs/using/agents/bee.md

@@ -36,8 +36,7 @@ To use MCP tools in the Bee Agent Framework, follow these steps:
 
    ```bash
    export MCP_GATEWAY_BASE_URL=http://localhost:4444
-   export MCP_AUTH_USER=admin
-   export MCP_AUTH_PASS=changeme
+   export MCP_AUTH_TOKEN="your_bearer_token"
    ```
 
 ---

docs/docs/using/clients/claude-desktop.md

@@ -33,8 +33,7 @@ Add this block to the `"mcpServers"` section of your config:
     "env": {
       "MCP_GATEWAY_BASE_URL": "http://localhost:4444",
       "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/2",
-      "MCP_AUTH_USER": "admin",
-      "MCP_AUTH_PASS": "changeme"
+      "MCP_AUTH_TOKEN": "your_bearer_token"
     }
   }
 }

docs/docs/using/clients/continue.md

@@ -55,8 +55,7 @@ Replace `"mcpgateway-wrapper"` with the appropriate command or path to your MCP
 
    * `MCP_GATEWAY_BASE_URL`: Base URL of your MCP Gateway (e.g., `http://localhost:4444`).
    * `MCP_SERVER_CATALOG_URLS`: URL(s) to the server catalog(s) (e.g., `http://localhost:4444/servers/2`).
-   * `MCP_AUTH_USER`: Username for authentication (e.g., `admin`).
-   * `MCP_AUTH_PASS`: Password for authentication (e.g., `changeme`).
+   * `MCP_AUTH_TOKEN`: JWT token used for authentication (as generated by `python3 -m mcpgateway.utils.create_jwt_token`).
 
    You can set these in your system environment or within the Continue configuration if supported.
 

docs/docs/using/clients/copilot.md

@@ -99,8 +99,7 @@ Point Copilot to the local wrapper process:
       "env": {
         "MCP_GATEWAY_BASE_URL": "http://localhost:4444",
         "MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/1",
-        "MCP_AUTH_USER": "admin",
-        "MCP_AUTH_PASS": "changeme"
+        "MCP_AUTH_TOKEN": "your_bearer_token"
       }
     }
   }

docs/docs/using/clients/mcp-inspector.md

@@ -38,13 +38,12 @@ npx @modelcontextprotocol/inspector \
 
 ## 🔐 Auth & Config
 
-Ensure you provide the necessary `MCP_AUTH_USER` and `MCP_AUTH_PASS` as environment variables if your gateway requires authentication:
+Ensure you provide the necessary `MCP_AUTH_TOKEN` as environment variable if your gateway requires authentication:
 
 ```bash
 export MCP_GATEWAY_BASE_URL=http://localhost:4444
 export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/2
-export MCP_AUTH_USER=admin
-export MCP_AUTH_PASS=changeme
+export MCP_AUTH_TOKEN="your_bearer_token"
 ```
 
 Then run the Inspector again.

mcpgateway/cli.py

@@ -17,7 +17,7 @@
 ─────────
 * Injects the default FastAPI application path (``mcpgateway.main:app``)
   when the user doesn't supply one explicitly.
-* Adds sensible default host/port (0.0.0.0:4444) unless the user passes
+* Adds sensible default host/port (127.0.0.1:4444) unless the user passes
   ``--host``/``--port`` or overrides them via the environment variables
   ``MCG_HOST`` and ``MCG_PORT``.
 * Forwards *all* remaining arguments verbatim to Uvicorn's own CLI, so
@@ -26,7 +26,7 @@
 Typical usage
 ─────────────
 ```console
-$ mcpgateway --reload                 # dev server on 0.0.0.0:4444
+$ mcpgateway --reload                 # dev server on 127.0.0.1:4444
 $ mcpgateway --workers 4              # production-style multiprocess
 $ mcpgateway 127.0.0.1:8000 --reload  # explicit host/port keeps defaults out
 $ mcpgateway mypkg.other:app          # run a different ASGI callable
@@ -45,7 +45,7 @@
 # Configuration defaults (overridable via environment variables)
 # ---------------------------------------------------------------------------
 DEFAULT_APP = "mcpgateway.main:app"  # dotted path to FastAPI instance
-DEFAULT_HOST = os.getenv("MCG_HOST", "0.0.0.0")
+DEFAULT_HOST = os.getenv("MCG_HOST", "127.0.0.1")
 DEFAULT_PORT = int(os.getenv("MCG_PORT", "4444"))
 
 # ---------------------------------------------------------------------------

mcpgateway/config.py

@@ -75,7 +75,7 @@ class Settings(BaseSettings):
     token_expiry: int = 10080  # minutes
 
     #  Encryption key phrase for auth storage
-    auth_encryption_secret: str = "my-test-key"
+    auth_encryption_secret: str = "my-test-salt"
 
     # UI/Admin Feature Flags
     mcpgateway_ui_enabled: bool = True