Plugin System Overview

Architecture

The Secure MCP Gateway uses a flexible plugin-based architecture to support custom authentication, guardrails, and telemetry providers. This design allows you to extend the gateway’s functionality without modifying core code.

Plugin Types

The gateway supports three types of plugins:

Auth Providers

Validate API keys, OAuth tokens, JWT, and custom credentials

Guardrail Providers

Detect PII, toxicity, policy violations, and security threats

Telemetry Providers

Export logs, traces, and metrics to observability platforms

Plugin Discovery

Plugins are loaded dynamically using the PluginLoader class. The loader:

Reads plugin configuration from plugins section in config file
Instantiates the specified provider class
Registers the provider with the appropriate manager
Falls back to default Enkrypt providers if custom providers fail

Configuration Structure

{
  "plugins": {
    "auth": {
      "provider": "local_apikey",
      "config": {
        "use_remote_config": false
      }
    },
    "guardrails": {
      "provider": "enkrypt",
      "config": {
        "api_key": "YOUR_API_KEY",
        "base_url": "https://api.enkryptai.com"
      }
    },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  }
}

Creating a Custom Plugin

Step 1: Implement the Provider Interface

Create a new Python file with your provider class implementing the appropriate abstract base class:

from secure_mcp_gateway.plugins.auth.base import (
    AuthProvider,
    AuthCredentials,
    AuthResult,
    AuthStatus,
    AuthMethod
)

class MyCustomAuthProvider(AuthProvider):
    def __init__(self, api_key: str, base_url: str):
        self.api_key = api_key
        self.base_url = base_url
    
    def get_name(self) -> str:
        return "my-custom-auth"
    
    def get_version(self) -> str:
        return "1.0.0"
    
    def get_supported_methods(self) -> List[AuthMethod]:
        return [AuthMethod.API_KEY]
    
    async def authenticate(self, credentials: AuthCredentials) -> AuthResult:
        # Your authentication logic here
        pass
    
    async def validate_session(self, session_id: str) -> bool:
        # Your session validation logic
        pass
    
    async def refresh_authentication(
        self, session_id: str, credentials: AuthCredentials
    ) -> AuthResult:
        # Your refresh logic
        pass

Step 2: Register Your Plugin

Update your configuration to use the custom provider:

{
  "plugins": {
    "auth": {
      "provider": "my-custom-auth",
      "config": {
        "api_key": "your-key",
        "base_url": "https://api.example.com"
      }
    }
  }
}

Step 3: Make Your Provider Discoverable

Add your provider to the plugin loader mapping in plugin_loader.py:55:

provider_class_mapping = {
    "my-custom-auth": "my_package.my_module.MyCustomAuthProvider",
    # ... other providers
}

Design Patterns

Registry Pattern

Each plugin type uses a registry to manage provider instances:

from secure_mcp_gateway.plugins.auth.base import AuthProviderRegistry

registry = AuthProviderRegistry()
registry.register(my_provider)
provider = registry.get_provider("my-custom-auth")

Factory Pattern

The GuardrailFactory creates guardrail instances from registered providers:

from secure_mcp_gateway.plugins.guardrails.base import GuardrailFactory

factory = GuardrailFactory(registry)
input_guardrail = factory.create_input_guardrail("enkrypt", config)

Protocol/Interface Segregation

Guardrail providers use multiple protocols for different capabilities:

InputGuardrail - Validates requests before execution
OutputGuardrail - Validates responses after execution
PIIHandler - Handles PII detection and redaction

This allows providers to implement only the features they support.

Plugin Lifecycle

Initialization

Gateway Startup - gateway.py loads common config
Plugin Loading - PluginLoader.load_plugin_providers() discovers providers
Registration - Providers registered with manager instances
Validation - Provider config validated with validate_config()

Request Processing

Credential Extraction - Auth manager extracts credentials from request
Authentication - Auth provider validates credentials
Tool Discovery - Gateway discovers available tools
Input Guardrails - Request validated before execution (optional)
Tool Execution - MCP tool executed via client
Output Guardrails - Response validated after execution (optional)
Telemetry - Events logged/traced throughout

Shutdown

Telemetry providers can implement shutdown() for cleanup:

def shutdown(self) -> TelemetryResult:
    # Close connections, flush buffers, etc.
    return TelemetryResult(
        success=True,
        provider_name=self.name,
        message="Shutdown successful"
    )

Best Practices

Error Handling

Always wrap provider operations in try/except blocks and return appropriate status codes:

try:
    # Your logic
    return AuthResult(
        status=AuthStatus.SUCCESS,
        authenticated=True,
        message="Success"
    )
except Exception as e:
    return AuthResult(
        status=AuthStatus.ERROR,
        authenticated=False,
        message="Failed",
        error=str(e)
    )

Sensitive Data Masking

Never log sensitive credentials. Use masking utilities:

from secure_mcp_gateway.utils import mask_sensitive_data

safe_data = mask_sensitive_data({
    "api_key": "secret123",
    "user": "john"
})
# {"api_key": "****123", "user": "john"}

Configuration Validation

Implement validate_config() to check required fields:

def validate_config(self, config: Dict[str, Any]) -> bool:
    required = ["api_key", "base_url"]
    return all(key in config for key in required)

def get_required_config_keys(self) -> List[str]:
    return ["api_key", "base_url"]

Async Operations

Use async/await for I/O operations:

async def authenticate(self, credentials: AuthCredentials) -> AuthResult:
    async with httpx.AsyncClient() as client:
        response = await client.post(self.auth_url, json=data)
        # Process response

Default Providers

The gateway includes these default providers:

Plugin Type	Provider	Description
Auth	`local_apikey`	Validates API keys from local config file
Auth	`enkrypt`	Remote authentication via Enkrypt API
Guardrails	`enkrypt`	Production guardrail service with 10+ detectors
Telemetry	`opentelemetry`	Full OpenTelemetry with OTLP export

The PluginLoader automatically falls back to default Enkrypt providers if custom providers fail to load.

Next Steps

Auth Providers

Learn about the AuthProvider interface

Guardrail Providers

Build custom security guardrails

Telemetry Providers

Integrate custom observability backends

REST API

CLI Reference

Gateway Tools

Plugin API

Architecture

Plugin Types

Auth Providers

Guardrail Providers

Telemetry Providers

Plugin Discovery

Configuration Structure

Creating a Custom Plugin

Step 1: Implement the Provider Interface

Step 2: Register Your Plugin

Step 3: Make Your Provider Discoverable

Design Patterns

Registry Pattern

Factory Pattern

Protocol/Interface Segregation

Plugin Lifecycle

Initialization

Request Processing

Shutdown

Best Practices

Default Providers

Next Steps

Auth Providers

Guardrail Providers

Telemetry Providers

​Architecture

​Plugin Types

Auth Providers

Guardrail Providers

Telemetry Providers

​Plugin Discovery

​Configuration Structure

​Creating a Custom Plugin

​Step 1: Implement the Provider Interface

​Step 2: Register Your Plugin

​Step 3: Make Your Provider Discoverable

​Design Patterns

​Registry Pattern

​Factory Pattern

​Protocol/Interface Segregation

​Plugin Lifecycle

​Initialization

​Request Processing

​Shutdown

​Best Practices

​Default Providers

​Next Steps

Auth Providers

Guardrail Providers

Telemetry Providers

Architecture

Plugin Types

Plugin Discovery

Configuration Structure

Creating a Custom Plugin

Step 1: Implement the Provider Interface

Step 2: Register Your Plugin

Step 3: Make Your Provider Discoverable

Design Patterns

Registry Pattern

Factory Pattern

Protocol/Interface Segregation

Plugin Lifecycle

Initialization

Request Processing

Shutdown

Best Practices

Default Providers

Next Steps