Implement Session Persistence

.env.example

@@ -209,6 +209,55 @@ OAUTH_MAX_RETRIES=3
 # tokens are stored per-user to prevent cross-user token access.
 # Users must individually authorize each OAuth-protected gateway.
 
+#####################################
+# OAuth Dynamic Client Registration (DCR) and PKCE
+#####################################
+
+# Enable Dynamic Client Registration (RFC 7591)
+# When enabled, MCP Gateway can automatically register as an OAuth client with Authorization Servers
+# that support DCR, eliminating the need for manual client credential configuration.
+MCPGATEWAY_DCR_ENABLED=true
+
+# Auto-register when gateway has issuer but no client_id
+# When true, gateway automatically registers with the Authorization Server when configured
+# with an issuer URL but no client credentials.
+MCPGATEWAY_DCR_AUTO_REGISTER_ON_MISSING_CREDENTIALS=true
+
+# Default scopes to request during DCR
+# Comma-separated list of OAuth scopes to request when auto-registering
+MCPGATEWAY_DCR_DEFAULT_SCOPES=mcp:read
+
+# Optional allowlist of issuer URLs for DCR (empty = allow any)
+# Comma-separated list of trusted Authorization Server issuer URLs
+# Example: https://auth.example.com,https://auth2.example.com
+# Leave empty to allow DCR with any issuer (not recommended for production)
+MCPGATEWAY_DCR_ALLOWED_ISSUERS=
+
+# Token endpoint authentication method for DCR
+# Options: client_secret_basic (default), client_secret_post, none
+# - client_secret_basic: Send credentials via HTTP Basic Auth header
+# - client_secret_post: Send credentials in POST body
+# - none: Public client (no client secret, PKCE-only)
+MCPGATEWAY_DCR_TOKEN_ENDPOINT_AUTH_METHOD=client_secret_basic
+
+# AS metadata cache TTL in seconds (RFC 8414 discovery)
+# How long to cache Authorization Server metadata after discovery
+MCPGATEWAY_DCR_METADATA_CACHE_TTL=3600
+
+# Template for client_name in DCR requests
+# {gateway_name} will be replaced with the actual gateway name
+MCPGATEWAY_DCR_CLIENT_NAME_TEMPLATE=MCP Gateway ({gateway_name})
+
+# Enable OAuth AS metadata discovery (RFC 8414)
+# When enabled, gateway automatically discovers Authorization Server endpoints
+# from the issuer URL using well-known metadata endpoints
+MCPGATEWAY_OAUTH_DISCOVERY_ENABLED=true
+
+# Preferred PKCE code challenge method
+# Options: S256 (SHA-256, recommended), plain (not recommended)
+# PKCE (Proof Key for Code Exchange) is always enabled for Authorization Code flows
+MCPGATEWAY_OAUTH_PREFERRED_CODE_CHALLENGE_METHOD=S256
+
 # ==============================================================================
 # SSO (Single Sign-On) Configuration
 # ==============================================================================
@@ -322,6 +371,34 @@ MCPGATEWAY_A2A_MAX_RETRIES=3
 # Enable A2A agent metrics collection (true/false)
 MCPGATEWAY_A2A_METRICS_ENABLED=true
 
+#####################################
+# MCP Server Catalog Configuration
+#####################################
+
+# Enable MCP server catalog feature (NEW in v0.7.0)
+# Allows defining a catalog of pre-configured MCP servers in a YAML file
+# for easy discovery and management via the Admin UI
+# Options: true (default), false
+MCPGATEWAY_CATALOG_ENABLED=true
+
+# Path to the catalog configuration file
+# YAML file containing MCP server definitions
+# Default: mcp-catalog.yml
+MCPGATEWAY_CATALOG_FILE=mcp-catalog.yml
+
+# Automatically health check catalog servers on startup and periodically
+# Options: true (default), false
+MCPGATEWAY_CATALOG_AUTO_HEALTH_CHECK=true
+
+# Catalog cache TTL in seconds
+# How long to cache catalog data before refreshing
+# Default: 3600 (1 hour)
+MCPGATEWAY_CATALOG_CACHE_TTL=3600
+
+# Number of catalog servers to display per page
+# Default: 100
+MCPGATEWAY_CATALOG_PAGE_SIZE=100
+
 #####################################
 # Header Passthrough Configuration
 #####################################
@@ -493,6 +570,20 @@ SSE_KEEPALIVE_INTERVAL=30
 # false: Stateless mode (better for scaling)
 USE_STATEFUL_SESSIONS=false
 
+####################################
+# Session Pooling (SSE/WS)
+####################################
+# Enable session pooling for SSE/WS (default: false)
+SESSION_POOLING_ENABLED=false
+# Comma-separated list of server IDs for which pooling is enabled (overrides global)
+SESSION_POOLING_SERVERS=[]
+# Max idle time (seconds) before pooled session is evicted (default: 600)
+SESSION_POOL_MAX_IDLE=600
+# Max pooled sessions per user (default: 10)
+SESSION_POOL_USER_LIMIT=10
+
+
+
 # Enable JSON response format for streaming HTTP
 # Options: true (default), false
 # true: Return JSON responses, false: Return SSE stream
@@ -513,7 +604,8 @@ FEDERATION_DISCOVERY=false
 FEDERATION_PEERS=[]
 
 # Timeout for federation requests in seconds
-FEDERATION_TIMEOUT=30
+# Default: 120 seconds (matches config.py)
+FEDERATION_TIMEOUT=120
 
 # Interval between federation sync operations in seconds
 FEDERATION_SYNC_INTERVAL=300
@@ -544,9 +636,11 @@ PROMPT_RENDER_TIMEOUT=10
 
 # Health Check Configuration
 HEALTH_CHECK_INTERVAL=60
-HEALTH_CHECK_TIMEOUT=15
+# Health check timeout in seconds (default: 10, matches config.py)
+HEALTH_CHECK_TIMEOUT=10
 UNHEALTHY_THRESHOLD=5
-GATEWAY_VALIDATION_TIMEOUT=10
+# Gateway URL validation timeout in seconds (default: 5, matches config.py)
+GATEWAY_VALIDATION_TIMEOUT=5
 
 # File lock name for gateway service leader election
 # Used to coordinate multiple gateway instances when running in cluster mode

MANIFEST.in

@@ -169,7 +169,7 @@ exclude plugins/external/opa/.env.template
 exclude plugins/external/opa/.ruff.toml
 exclude plugins/external/opa/Containerfile
 exclude plugins/external/opa/MANIFEST.in
-exclude plugins/external/opa/opaserver/rego/example.rego
+exclude plugins/external/opa/opaserver/rego/policy.rego
 exclude plugins/external/opa/pyproject.toml
 exclude plugins/external/opa/run-server.sh
 
@@ -179,6 +179,5 @@ exclude plugins/external/llmguard/.env.template
 exclude plugins/external/llmguard/.ruff.toml
 exclude plugins/external/llmguard/Containerfile
 exclude plugins/external/llmguard/MANIFEST.in
-exclude plugins/external/llmguard/opaserver/rego/example.rego
 exclude plugins/external/llmguard/pyproject.toml
 exclude plugins/external/llmguard/run-server.sh

README.md

@@ -379,7 +379,7 @@ python3 -m mcpgateway.translate \
 # 2️⃣  Register it with the gateway
 curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
-     -d '{"name":"fast_time","url":"http://localhost:9000/sse"}' \
+     -d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \
      http://localhost:4444/gateways
 
 # 3️⃣  Verify tool catalog
@@ -462,6 +462,7 @@ When using a MCP Client such as Claude with stdio:
 ## Quick Start - Containers
 
 Use the official OCI image from GHCR with **Docker** *or* **Podman**.
+Please note: Currently, arm64 is not supported. If you are e.g. running on MacOS, install via PyPi.
 
 ---
 
@@ -1255,20 +1256,35 @@ You can get started by copying the provided [.env.example](https://github.com/IB
 | ------------------------------ | ------------------------------------------------ | --------------------- | ------- |
 | `SSO_AUTO_ADMIN_DOMAINS`      | Email domains that automatically get admin privileges | `[]`             | JSON array |
 
-### Dynamic Client Registration & Virtual MCP Server Authentication
-
-ContextForge supports OAuth2 with Dynamic Client Registration (DCR)
-for streamable HTTP servers through integration with an upstream API gateway,
-such as HyperMCP gateway, enabling automatic OAuth2 client provisioning for MCP servers
-without manual configuration.
-
-| Setting                     | Description                                            | Default | Options |
-|-----------------------------|--------------------------------------------------------|---------|---------|
-| `JWT_AUDIENCE_VERIFICATION` | JWT audience verification needs to be disabled for DCR | `true`  | bool    |
-
-You can find an example for using dynamic client registration (DCR) with [HyprMCP Gateway (`hyprmcp/mcp-gateway`)](https://github.com/hyprmcp/mcp-gateway).
-
-Follow the tutorial at https://ibm.github.io/mcp-context-forge/tutorials/dcr-hyprmcp/ to get started.
+### OAuth 2.0 Dynamic Client Registration (DCR) & PKCE
+
+ContextForge implements **OAuth 2.0 Dynamic Client Registration (RFC 7591)** and **PKCE (RFC 7636)** for seamless integration with OAuth-protected MCP servers and upstream API gateways like HyperMCP.
+
+**Key Features:**
+- ✅ Automatic client registration with Authorization Servers (no manual credential configuration)
+- ✅ Authorization Server metadata discovery (RFC 8414)
+- ✅ PKCE (Proof Key for Code Exchange) enabled for all Authorization Code flows
+- ✅ Support for public clients (PKCE-only, no client secret)
+- ✅ Encrypted credential storage with Fernet encryption
+- ✅ Configurable issuer allowlist for security
+
+| Setting                                                | Description                                                    | Default                        | Options       |
+|-------------------------------------------------------|----------------------------------------------------------------|--------------------------------|---------------|
+| `MCPGATEWAY_DCR_ENABLED`                              | Enable Dynamic Client Registration (RFC 7591)                  | `true`                         | bool          |
+| `MCPGATEWAY_DCR_AUTO_REGISTER_ON_MISSING_CREDENTIALS` | Auto-register when gateway has issuer but no client_id         | `true`                         | bool          |
+| `MCPGATEWAY_DCR_DEFAULT_SCOPES`                       | Default OAuth scopes to request during DCR                     | `mcp:read`                     | string        |
+| `MCPGATEWAY_DCR_ALLOWED_ISSUERS`                      | Allowlist of trusted issuer URLs (empty = allow any)           | `[]`                           | JSON array    |
+| `MCPGATEWAY_DCR_TOKEN_ENDPOINT_AUTH_METHOD`           | Token endpoint auth method                                     | `client_secret_basic`          | `client_secret_basic`, `client_secret_post`, `none` |
+| `MCPGATEWAY_DCR_METADATA_CACHE_TTL`                   | AS metadata cache TTL in seconds                               | `3600`                         | int           |
+| `MCPGATEWAY_DCR_CLIENT_NAME_TEMPLATE`                 | Template for client_name in DCR requests                       | `MCP Gateway ({gateway_name})` | string        |
+| `MCPGATEWAY_OAUTH_DISCOVERY_ENABLED`                  | Enable AS metadata discovery (RFC 8414)                        | `true`                         | bool          |
+| `MCPGATEWAY_OAUTH_PREFERRED_CODE_CHALLENGE_METHOD`    | PKCE code challenge method                                     | `S256`                         | `S256`, `plain` |
+| `JWT_AUDIENCE_VERIFICATION`                           | JWT audience verification (disable for DCR)                    | `true`                         | bool          |
+
+**Documentation:**
+- [DCR Configuration Guide](https://ibm.github.io/mcp-context-forge/manage/dcr/) - Complete DCR setup and troubleshooting
+- [OAuth 2.0 Integration](https://ibm.github.io/mcp-context-forge/manage/oauth/) - OAuth configuration and PKCE details
+- [HyperMCP Tutorial](https://ibm.github.io/mcp-context-forge/tutorials/dcr-hyprmcp/) - End-to-end DCR setup with HyperMCP gateway
 
 ### Personal Teams Configuration
 
@@ -1281,6 +1297,29 @@ Follow the tutorial at https://ibm.github.io/mcp-context-forge/tutorials/dcr-hyp
 | `INVITATION_EXPIRY_DAYS`                 | Number of days before team invitations expire   | `7`        | int > 0 |
 | `REQUIRE_EMAIL_VERIFICATION_FOR_INVITES` | Require email verification for team invitations | `true`     | bool    |
 
+### MCP Server Catalog
+
+> 🆕 **New in v0.7.0**: The MCP Server Catalog allows you to define a catalog of pre-configured MCP servers in a YAML file for easy discovery and management via the Admin UI.
+
+| Setting                              | Description                                      | Default            | Options |
+| ------------------------------------ | ------------------------------------------------ | ------------------ | ------- |
+| `MCPGATEWAY_CATALOG_ENABLED`        | Enable MCP server catalog feature                | `true`             | bool    |
+| `MCPGATEWAY_CATALOG_FILE`           | Path to catalog configuration file               | `mcp-catalog.yml`  | string  |
+| `MCPGATEWAY_CATALOG_AUTO_HEALTH_CHECK` | Automatically health check catalog servers    | `true`             | bool    |
+| `MCPGATEWAY_CATALOG_CACHE_TTL`      | Catalog cache TTL in seconds                     | `3600`             | int > 0 |
+| `MCPGATEWAY_CATALOG_PAGE_SIZE`      | Number of catalog servers per page               | `12`               | int > 0 |
+
+**Key Features:**
+- 🔄 Refresh Button - Manually refresh catalog without page reload
+- 🔍 Debounced Search - Optimized search with 300ms debounce
+- 📝 Custom Server Names - Specify custom names when registering
+- 🔌 Transport Detection - Auto-detect SSE, WebSocket, or HTTP transports
+- 🔐 OAuth Support - Register OAuth servers and configure later
+- ⚡ Better Error Messages - User-friendly errors for common issues
+
+**Documentation:**
+- [MCP Server Catalog Guide](https://ibm.github.io/mcp-context-forge/manage/catalog/) - Complete catalog setup and configuration
+
 ### Security
 
 | Setting                   | Description                    | Default                                        | Options    |

docs/docs/architecture/adr/.pages

@@ -1,5 +1,6 @@
 title: Decision Records
 nav:
+  - Overview: index.md
   - 1 Adopt FastAPI + Pydantic: 001-adopt-fastapi-pydantic.md
   - 2 Use Async SQLAlchemy ORM: 002-use-async-sqlalchemy-orm.md
   - 3 Expose Multi-Transport Endpoints: 003-expose-multi-transport-endpoints.md
@@ -8,7 +9,7 @@ nav:
   - 6 Gateway & Tool-Level Rate Limiting: 006-gateway-tool-rate-limiting.md
   - 7 Pluggable Cache Backend: 007-pluggable-cache-backend.md
   - 8 Federation & Auto-Discovery via DNS-SD: 008-federation-discovery.md
-  - 9 Built-in Health Checks: 000-built-in-health-checks.md
+  - 9 Built-in Health Checks: 009-built-in-health-checks.md
   - 10 Observability via Prometheus: 010-observability-prometheus.md
   - 11 Namespaced Tool Federation: 011-tool-federation.md
   - 12 Drop-down tool selection: 012-dropdown-ui-tool-selection.md

docs/docs/architecture/plugins.md

@@ -638,7 +638,7 @@ class PluginMode(str, Enum):
     DISABLED = "disabled"            # Plugin loaded but not executed
 
 class HookType(str, Enum):
-    """Available hook points in MCP request lifecycle"""    
+    """Available hook points in MCP request lifecycle"""
     PROMPT_PRE_FETCH = "prompt_pre_fetch"     # Before prompt retrieval
     PROMPT_POST_FETCH = "prompt_post_fetch"   # After prompt rendering
     TOOL_PRE_INVOKE = "tool_pre_invoke"       # Before tool execution

docs/docs/manage/.pages

@@ -1,7 +1,10 @@
 nav:
   - index.md
   - configuration.md
+  - scale.md
+  - tuning.md
   - backup.md
+  - catalog.md
   - bulk-import.md
   - metadata-tracking.md
   - export-import.md
@@ -20,7 +23,8 @@ nav:
   - sso-google-tutorial.md
   - sso-ibm-tutorial.md
   - sso-okta-tutorial.md
-  - tuning.md
+  - rbac.md
+  - teams.md
   - ui-customization.md
   - upgrade.md
   - well-known-uris.md