Add comprehensive mTLS documentation and plugin TLS support

.env.example

@@ -603,6 +603,15 @@ PLUGINS_ENABLED=false
 # Default: plugins/config.yaml
 PLUGIN_CONFIG_FILE=plugins/config.yaml
 
+# Optional defaults for mTLS when connecting to external MCP plugins (STREAMABLEHTTP transport)
+# Provide file paths inside the container. Plugin-specific TLS blocks override these defaults.
+# PLUGINS_MTLS_CA_BUNDLE=/app/certs/plugins/ca.crt
+# PLUGINS_MTLS_CLIENT_CERT=/app/certs/plugins/gateway-client.pem
+# PLUGINS_MTLS_CLIENT_KEY=/app/certs/plugins/gateway-client.key
+# PLUGINS_MTLS_CLIENT_KEY_PASSWORD=
+# PLUGINS_MTLS_VERIFY=true
+# PLUGINS_MTLS_CHECK_HOSTNAME=true
+
 #####################################
 # Well-Known URI Configuration
 #####################################

README.md

@@ -1581,6 +1581,12 @@ MCP Gateway uses Alembic for database migrations. Common commands:
 | ------------------------------ | ------------------------------------------------ | --------------------- | ------- |
 | `PLUGINS_ENABLED`             | Enable the plugin framework                      | `false`               | bool    |
 | `PLUGIN_CONFIG_FILE`          | Path to main plugin configuration file          | `plugins/config.yaml` | string  |
+| `PLUGINS_MTLS_CA_BUNDLE`      | (Optional) default CA bundle for external plugin mTLS | _(empty)_     | string  |
+| `PLUGINS_MTLS_CLIENT_CERT`    | (Optional) gateway client certificate for plugin mTLS | _(empty)_     | string  |
+| `PLUGINS_MTLS_CLIENT_KEY`     | (Optional) gateway client key for plugin mTLS | _(empty)_             | string  |
+| `PLUGINS_MTLS_CLIENT_KEY_PASSWORD` | (Optional) password for plugin client key | _(empty)_             | string  |
+| `PLUGINS_MTLS_VERIFY`         | (Optional) verify remote plugin certificates (`true`/`false`) | `true` | bool    |
+| `PLUGINS_MTLS_CHECK_HOSTNAME` | (Optional) enforce hostname verification for plugins | `true`      | bool    |
 | `PLUGINS_CLI_COMPLETION`      | Enable auto-completion for plugins CLI          | `false`               | bool    |
 | `PLUGINS_CLI_MARKUP_MODE`     | Set markup mode for plugins CLI                 | (none)                | `rich`, `markdown`, `disabled` |
 

charts/mcp-stack/values.yaml

@@ -267,6 +267,12 @@ mcpContextForge:
     # ─ Plugin Configuration ─
     PLUGINS_ENABLED: "false"         # enable the plugin framework
     PLUGIN_CONFIG_FILE: "plugins/config.yaml" # path to main plugin configuration file
+    PLUGINS_MTLS_CA_BUNDLE: ""               # default CA bundle for external plugins (optional)
+    PLUGINS_MTLS_CLIENT_CERT: ""             # gateway client certificate for plugin mTLS
+    PLUGINS_MTLS_CLIENT_KEY: ""              # gateway client key for plugin mTLS (optional)
+    PLUGINS_MTLS_CLIENT_KEY_PASSWORD: ""     # password for the plugin client key (optional)
+    PLUGINS_MTLS_VERIFY: "true"              # verify remote plugin certificates
+    PLUGINS_MTLS_CHECK_HOSTNAME: "true"      # enforce hostname verification when verifying certs
     PLUGINS_CLI_COMPLETION: "false"  # enable auto-completion for plugins CLI
     PLUGINS_CLI_MARKUP_MODE: ""      # set markup mode for plugins CLI
 

docs/docs/architecture/plugin-spec/.pages

@@ -14,4 +14,4 @@ nav:
   - Performance: 11-performance.md
   - Development: 12-development.md
   - Testing: 13-testing.md
-  - Conclusion: 14-conclusion.md
+  - Conclusion: 14-conclusion.md

docs/docs/architecture/plugin-spec/01-architecture.md

@@ -75,4 +75,3 @@ mcpgateway/plugins/framework/
 - Communicate via MCP protocol over various transports
 - 10-100ms latency depending on service and network
 - Examples: LlamaGuard, OpenAI Moderation, custom AI services
-

docs/docs/architecture/plugin-spec/02-core-components.md

@@ -3,7 +3,7 @@
 
 ### 3.1 Plugin Base Class
 
-The base plugin class, of which developers subclass and implement the hooks that are important for their plugins. Hook points are functions that appear interpose on existing MCP and agent-based functionality. 
+The base plugin class, of which developers subclass and implement the hooks that are important for their plugins. Hook points are functions that appear interpose on existing MCP and agent-based functionality.
 
 ```python
 class Plugin:
@@ -122,4 +122,3 @@ class PluginInstanceRegistry:
     async def shutdown(self) -> None:
         """Shutdown all registered plugins"""
 ```
-

docs/docs/architecture/plugin-spec/03-plugin-types.md

@@ -37,7 +37,7 @@ The configuration system supports both **native plugins** (running in-process) a
 
 ### 4.2 Plugin Configuration Schema
 
-Below is an example of a plugin configuration file.  A plugin configuration file can configure one or more plugins in a prioritized list as below.  Each individual plugin is an instance of the of a plugin class that subclasses the base `Plugin` object and implements a set of hooks as listed in the configuration.   
+Below is an example of a plugin configuration file.  A plugin configuration file can configure one or more plugins in a prioritized list as below.  Each individual plugin is an instance of the of a plugin class that subclasses the base `Plugin` object and implements a set of hooks as listed in the configuration.
 
 ```yaml
 # plugins/config.yaml
@@ -408,4 +408,3 @@ The manifest enables development tools to provide:
 - Follow established tag conventions within your organization
 
 The plugin manifest system provides a foundation for plugin ecosystem management, enabling better development workflows, automated tooling, and enhanced discoverability while maintaining consistency across plugin implementations.
-

docs/docs/architecture/plugin-spec/04-hook-architecture.md

@@ -186,7 +186,7 @@ return PluginResult(
 
 **Processing Model**:
 
-Plugin processing uses short circuiting to abort evaluation in the case of a violation and `continue_processing=False`. If the plugin needs to record side effects, such as the bookkeeping, these plugins should be executed first with the highest priority. 
+Plugin processing uses short circuiting to abort evaluation in the case of a violation and `continue_processing=False`. If the plugin needs to record side effects, such as the bookkeeping, these plugins should be executed first with the highest priority.
 
 ### 5.2 HTTP Header Hook Integration Example
 
@@ -477,4 +477,3 @@ async def process_elicitation_response(self, response: ElicitationResponse) -> b
 
     return True
 ```
-

docs/docs/architecture/plugin-spec/05-hook-system.md

@@ -184,4 +184,3 @@ This document covers administrative operation hooks:
 - Gateway Federation Hooks - Peer gateway management *(Future)*
 - A2A Agent Hooks - Agent-to-Agent integration management *(Future)*
 - Entity Lifecycle Hooks - Tool, resource, and prompt registration *(Future)*
-

docs/docs/architecture/plugin-spec/06-gateway-hooks.md

@@ -1667,4 +1667,3 @@ The gateway administrative hooks are organized into the following categories:
 - Implement proper timeout handling for elicitations
 - Cache frequently accessed data (permissions, quotas)
 - Use background tasks for non-critical operations
-

docs/docs/architecture/plugin-spec/07-security-hooks.md

@@ -758,4 +758,3 @@ async def resource_post_fetch(self, payload: ResourcePostFetchPayload, context:
 - Resource post-fetch may take longer due to content processing
 - Plugin execution is sequential within priority bands
 - Failed plugins don't affect other plugins (isolation)
-

docs/docs/architecture/plugin-spec/08-external-plugins.md

@@ -112,6 +112,11 @@ plugins:
     mcp:
       proto: "STREAMABLEHTTP"
       url: "http://localhost:8000/mcp"
+      # Optional TLS block when the remote server requires mTLS
+      # tls:
+      #   ca_bundle: /app/certs/plugins/ca.crt
+      #   client_cert: /app/certs/plugins/gateway-client.pem
+      #   client_key: /app/certs/plugins/gateway-client.key
 ```
 
 ### 7.2 MCP Protocol Integration
@@ -178,10 +183,21 @@ plugins:
     mcp:
       proto: "STREAMABLEHTTP"          # Transport protocol
       url: "http://openai-plugin:3000/mcp"  # Server URL
+      # Optional mutual TLS configuration
+      # tls:
+      #   ca_bundle: /app/certs/plugins/ca.crt
+      #   client_cert: /app/certs/plugins/gateway-client.pem
+      #   verify: true
       # Optional authentication
       auth:
         type: "bearer"
         token: "${OPENAI_API_KEY}"
+
+If you prefer centralised defaults, set the environment variables
+`PLUGINS_MTLS_CA_BUNDLE`, `PLUGINS_MTLS_CLIENT_CERT`, and related
+settings. These values apply whenever a plugin omits its own `tls`
+section, allowing a single gateway-wide certificate bundle to be reused
+across multiple external plugins.
 ```
 
 ### 7.5 MCP Transport Types

docs/docs/architecture/plugin-spec/09-security.md

@@ -65,4 +65,3 @@ except Exception as e:
         raise PluginError(f"Plugin error: {plugin.name}")
     # Continue with next plugin in permissive mode
 ```
-

docs/docs/architecture/plugin-spec/10-error-handling.md

@@ -414,4 +414,3 @@ async def execute(self, plugins: list[PluginRef], ...) -> tuple[PluginResult[T],
                 raise PluginError(f"Plugin error: {plugin.name}")
             # Continue with next plugin
 ```
-

docs/docs/architecture/plugin-spec/11-performance.md

@@ -14,4 +14,3 @@
 - **Context management**: Handle 10,000+ concurrent request contexts
 - **Memory usage**: Base framework overhead <5MB
 - **Plugin loading**: Initialize plugins in <10 seconds
-

docs/docs/architecture/plugin-spec/12-development.md

@@ -286,4 +286,3 @@ class TestMyPlugin:
 - Include execution metrics
 - Provide health check endpoints
 - Support debugging modes
-

docs/docs/architecture/plugin-spec/13-testing.md

@@ -22,4 +22,3 @@ The plugin framework provides comprehensive testing support across multiple leve
 - Validate external plugin communication
 - Performance and load testing
 - Security validation
-

docs/docs/architecture/plugin-spec/14-conclusion.md

@@ -36,4 +36,3 @@ This specification defines a comprehensive, production-ready plugin framework fo
 
 This specification serves as the definitive guide for developing, deploying, and operating plugins within the MCP Context Forge ecosystem, ensuring consistency, security, and performance across all plugin implementations.
 **Document Version**: 1.0
-

docs/docs/architecture/plugin-spec/plugin-framework-specification.md

@@ -57,4 +57,3 @@ This specification covers:
 - **Plugin Manager**: Core service managing plugin lifecycle and execution
 - **Plugin Context**: Request-scoped state shared between plugins
 - **Plugin Configuration**: YAML-based plugin setup and parameters
-

docs/docs/architecture/plugins.md

@@ -839,6 +839,9 @@ plugins:
     mcp:
       proto: "STREAMABLEHTTP"
       url: "http://nodejs-plugin:3000/mcp"
+      # tls:
+      #   ca_bundle: /app/certs/plugins/ca.crt
+      #   client_cert: /app/certs/plugins/gateway-client.pem
 
   # Go plugin
   - name: "HighPerformanceFilter"
@@ -853,6 +856,12 @@ plugins:
     mcp:
       proto: "STREAMABLEHTTP"
       url: "http://rust-plugin:8080/mcp"
+      # tls:
+      #   verify: true
+
+Gateway-wide defaults for these TLS options can be supplied via the
+`PLUGINS_MTLS_*` environment variables when you want every external
+plugin to share the same client certificate and CA bundle.
 ```
 
 ## Remote Plugin MCP Server Integration

docs/docs/index.md

@@ -1435,6 +1435,12 @@ MCP Gateway uses Alembic for database migrations. Common commands:
 | ------------------------------ | ------------------------------------------------ | --------------------- | ------- |
 | `PLUGINS_ENABLED`             | Enable the plugin framework                      | `false`               | bool    |
 | `PLUGIN_CONFIG_FILE`          | Path to main plugin configuration file          | `plugins/config.yaml` | string  |
+| `PLUGINS_MTLS_CA_BUNDLE`      | (Optional) default CA bundle for external plugin mTLS | _(empty)_     | string  |
+| `PLUGINS_MTLS_CLIENT_CERT`    | (Optional) gateway client certificate for plugin mTLS | _(empty)_     | string  |
+| `PLUGINS_MTLS_CLIENT_KEY`     | (Optional) gateway client key for plugin mTLS | _(empty)_             | string  |
+| `PLUGINS_MTLS_CLIENT_KEY_PASSWORD` | (Optional) password for plugin client key | _(empty)_             | string  |
+| `PLUGINS_MTLS_VERIFY`         | (Optional) verify remote plugin certificates (`true`/`false`) | `true` | bool    |
+| `PLUGINS_MTLS_CHECK_HOSTNAME` | (Optional) enforce hostname verification for plugins | `true`      | bool    |
 | `PLUGINS_CLI_COMPLETION`      | Enable auto-completion for plugins CLI          | `false`               | bool    |
 | `PLUGINS_CLI_MARKUP_MODE`     | Set markup mode for plugins CLI                 | (none)                | `rich`, `markdown`, `disabled` |