Plugin Framework Specification

Plugin Framework Specification

Version: 1.0 Status: Stable

ContextForge Plugin Framework provides a comprehensive, production-ready system for extending ContextForge functionality through pluggable middleware components. These plugins interpose calls to MCP and agentic components to apply security, AI, business logic, and monitoring capabilities to existing flows. This specification defines the architecture, interfaces, and protocols for developing, deploying, and managing plugins within the MCP ecosystem.

Table of Contents

1. Overview
2. Architecture
3. Plugin Types and Configuration
4. Core Components
5. Hook System
6. Hook Reference Documentation
7. External Plugin Integration
8. Security and Protection
9. Performance Considerations
10. Development Guidelines
11. Testing
12. Platform-Agnostic Design
13. Future Extensions

Overview

The plugin framework is designed as a standalone, platform-agnostic ecosystem that can be embedded in any application requiring extensible middleware processing. It enables both native plugins (running in-process) and external plugin integrations (remote MCP servers) through a unified interface. This approach balances performance, security, and operational requirements while providing maximum flexibility for deployment across different environments and platforms.

Design Principles

1. Platform Agnostic: The Framework is implemented in Python, but external plugins can be implemented in any language of choice.
2. Protocol Neutral: Supports multiple transport mechanisms (Streamable HTTP (JSON-RPC), STDIO, SSE), and can be extended to support additional protocols
3. MCP Native: Remote plugins are fully compliant MCP servers
4. Security First: Comprehensive protection, validation, and isolation
5. Production Ready: Built for high-throughput, low-latency environments
6. Developer Friendly: Simple APIs with comprehensive tooling

Terminology

• Plugin: A middleware component that processes MCP requests/responses
• Hook: A specific point in the MCP lifecycle where plugins execute
• Native Plugin: Plugin running in-process with the gateway
• External Plugin: Plugin running as a remote MCP server
• 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

Features

Legend: ✅ = Completed | 🚧 = In Progress | 📋 = Planned

Plugin Lifecycle Management

• ✅ Discovery & Loading: Automatically discover and load plugins from configuration
• 📋 Dependency Resolution: Handle plugin dependencies and load order
• ✅ Runtime Control: Enable, disable, or modify plugin behavior without code changes
• ✅ Version Management: Track plugin versions and manage updates

Operational Control

• 🚧 Environment-Specific Deployment: Different configurations for dev/staging/production
• ✅ Conditional Execution: Run plugins only under specific conditions (tenant, server, user)
• ✅ Priority-Based Orchestration: Control execution order through priority settings
• ✅ Mode-Based Behavior: Switch between enforce/enforce_ignore_error/permissive/disabled modes

Security & Compliance

• ✅ Conditional Execution: Restrict plugin execution to specific users, tools, or servers
• ✅ Audit Trail: Track plugin configuration changes and deployment history
• ✅ Policy Enforcement: Implement organizational security policies through configuration
• 📋 External Service Integration: Securely configure connections to external AI safety services

Performance Optimization

• ✅ Resource Limits: Configure timeouts, memory limits, and execution constraints
• 📋 Selective Loading: Load only necessary plugins to optimize performance
• ✅ Monitoring Integration: Configure metrics collection and health monitoring
• 📋 Caching Strategies: Control plugin result caching and optimization

Architecture

The plugin framework implements an execution pipeline designed for enterprise-grade performance, security, and reliability.

Component View

Below is a view of the core components of the plugin system, which extends the gateway request execution pipeline with pre- and post- protocol hooks implemented by plugins.

flowchart TB
    subgraph "MCP Client"
        Client["MCP Client Application"]
    end

    subgraph GW["ContextForge"]
        Gateway["Gateway Core"]
        PM["Plugin Manager"]
        Executor["Plugin Executor"]
    end

    subgraph "Plugin Ecosystem"
        Native["Native Plugins"]
        External["External MCP <br> Plugin Servers"]
    end

    subgraph "External Services"
        AI["AI Safety Services<br>(LLM Guard, OpenAI Moderation)"]
        Security["Security Services<br>(Vault, OPA, Cedar)"]
    end

    Client --request--> GW
    GW --response--> Client
    Gateway --> PM
    PM --> Executor
    Executor --> Native
    Executor --> External
    External --> AI
    External --> Security

    style Gateway fill:#e3f2fd
    style PM fill:#fff3e0
    style Native fill:#e8f5e8
    style External fill:#fff8e1

Plugin Types and Configuration

The plugin configuration system provides a declarative, YAML-based approach to plugin management, deployment, and orchestration.

The configuration system supports both native plugins (running in-process) and external plugins (remote MCP servers), providing a unified interface for managing diverse plugin architectures while maintaining type safety, validation, and operational excellence.

Plugin Deployment Patterns

The framework supports two distinct plugin deployment patterns:

Native Plugins (In-Process)

• Execute within the main application process
• Written in Python and extend the base Plugin class
• Fastest execution with shared memory access
• Examples: regex filters, simple transforms, validation

External Plugins (Remote MCP Servers)

• Standalone MCP servers implementing plugin logic
• Can be written in any language (Python, TypeScript, Go, Rust, etc.)
• Communicate via MCP protocol (Streamable HTTP over TCP or UDS, STDIO, SSE)
• Examples: OPA filter, Cedar Policy Plugin (RBAC), LlamaGuard, OpenAI Moderation, custom AI services

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.

# plugins/config.yaml
plugins:

  - name: "PIIFilterPlugin"                    # Unique plugin identifier
    kind: "plugins.pii_filter.pii_filter.PIIFilterPlugin"  # Plugin class path
    description: "Detects and masks PII"       # Human-readable description
    version: "1.0.0"                          # Plugin version
    author: "Security Team"                   # Plugin author
    hooks:                                    # Hook registration

      - "prompt_pre_fetch"
      - "tool_pre_invoke"
      - "tool_post_invoke"
    tags:                                     # Searchable tags

      - "security"
      - "pii"
      - "compliance"
    mode: "enforce"                           # enforce|enforce_ignore_error|permissive|disabled
    priority: 50                              # Execution priority (lower = higher)
    conditions:                               # Conditional execution

      - server_ids: ["prod-server"]
        tenant_ids: ["enterprise"]
        tools: ["sensitive-tool"]
    config:                                   # Plugin-specific configuration
      detect_ssn: true
      detect_credit_card: true
      mask_strategy: "partial"
      redaction_text: "[REDACTED]"

# Global plugin settings
plugin_settings:
  parallel_execution_within_band: false      # Execute same-priority plugins in parallel
  plugin_timeout: 30                         # Per-plugin timeout (seconds)
  fail_on_plugin_error: false                # Continue on plugin failures
  plugin_health_check_interval: 60           # Health check interval (seconds)

Plugin Configuration Attributes

Details of each field are below:

Hook Types

Available hook values for the hooks field:

MCP Protocol Hooks:

HTTP Authentication & Middleware Hooks:

See the HTTP Authentication Hooks Guide for detailed implementation examples.

Plugin Modes

Available values for the mode field:

Condition Fields

The conditions array contains objects that specify when plugins should execute:

MCP Configuration Fields

For external plugins (kind: "external"), the mcp object configures the MCP server connection:

Global Plugin Settings

The plugin_settings object controls framework-wide behavior:

Plugin Manifest

The plugin manifest is a metadata file that provides structured information about a plugin's capabilities, dependencies, and characteristics. This manifest serves multiple purposes in the plugin ecosystem: development guidance, runtime validation, discoverability, and documentation.

Manifest Purpose and Usage

The plugin manifest (plugin-manifest.yaml) is primarily used by:

• Plugin Templates: Bootstrap process uses manifest to generate plugin scaffolding
• Plugin Catalog: Catalogs can provide enhanced search and organization based on manifest information
• Plugin Discovery: Registry systems can index plugins based on manifest metadata
• Documentation Generation: Automated documentation can be generated from manifest content
• Dependency Management: Future versions may use manifest for dependency resolution
• Security and Governance: Future versions may use manifest for specifying security capability requirements and storing signatures

Manifest Structure

The plugin manifest follows a structured YAML format that captures comprehensive plugin metadata:

# plugin-manifest.yaml
name: "Advanced PII Filter"
kind: "plugins.pii_filter.pii_filter.PIIFilterPlugin"
description: "Comprehensive PII detection and masking with configurable sensitivity levels"
author: "Security Engineering Team"
version: "2.1.0"
license: "MIT"
homepage: "https://github.com/company/advanced-pii-filter"
repository: "https://github.com/company/advanced-pii-filter.git"

# Plugin capabilities and hook registration
available_hooks:

  - "prompt_pre_fetch"
  - "prompt_post_fetch"
  - "tool_pre_invoke"
  - "tool_post_invoke"
  - "resource_post_fetch"

# Categorization and discovery
tags:

  - "security"
  - "pii"
  - "compliance"
  - "data-protection"
  - "gdpr"

# Plugin characteristics
plugin_type: "native"                    # native | external
language: "python"                       # python | typescript | go | rust | java
performance_tier: "high"                 # high | medium | low (expected latency)

# Default configuration template
default_config:
  detection_sensitivity: 0.8
  masking_strategy: "partial"             # partial | full | token
  pii_types:

    - "ssn"
    - "credit_card"
    - "email"
    - "phone"
  compliance_mode: "gdpr"                 # gdpr | hipaa | pci | custom
  log_violations: true
  max_content_length: 1048576

# Runtime requirements
requirements:
  python_version: ">=3.11"
  memory_mb: 64
  cpu_cores: 0.5
  timeout_seconds: 5

# Dependencies (for external plugins)
dependencies:

  - "spacy>=3.4.0"
  - "presidio-analyzer>=2.2.0"
  - "pydantic>=2.0.0"

# Plugin metadata for advanced features
features:
  configurable: true                      # Plugin accepts runtime configuration
  stateful: false                         # Plugin maintains state between requests
  async_capable: true                     # Plugin supports async execution
  external_dependencies: true             # Plugin requires external services
  multi_tenant: true                      # Plugin supports tenant isolation

# Documentation and examples
documentation:
  readme: "README.md"
  examples: "examples/"
  api_docs: "docs/api.md"

# Testing and quality assurance
testing:
  unit_tests: "tests/unit/"
  integration_tests: "tests/integration/"
  coverage_threshold: 80

# Compatibility and versioning
compatibility:
  min_framework_version: "1.0.0"
  max_framework_version: "2.x.x"
  python_versions: ["3.11", "3.12"]

# Optional deployment metadata
deployment:
  container_image: "company/pii-filter:2.1.0"
  k8s_manifest: "k8s/deployment.yaml"
  health_check_endpoint: "/health"

Manifest Fields Reference

Plugin Capability Fields

Configuration and Dependencies

Core Components

Core Framework Structure

mcpgateway/plugins/framework/
├── base.py              # Plugin base classes and PluginRef
├── models.py            # Pydantic models for all plugin types
├── manager.py           # PluginManager singleton with lifecycle management
├── registry.py          # Plugin instance registry and discovery
├── constants.py         # Framework constants and enums
├── errors.py            # Plugin-specific exception types
├── utils.py             # Utility functions for plugin operations
├── loader/
│   ├── config.py        # Configuration loading and validation
│   └── plugin.py        # Dynamic plugin loading and instantiation
└── external/
    └── mcp/             # MCP external service integration
        ├── client.py    # MCP client for external plugin communication
        └── server/      # MCP server runtime for plugin hosting
            ├── server.py    # MCP server implementation
            └── runtime.py   # Plugin runtime management

Base Plugin Class

The Plugin class is an Abstract Base Class (ABC) that provides the foundation for all plugins. Developers must subclass it and implement only the hooks they need using one of three registration patterns.

from abc import ABC

class Plugin(ABC):
    """Abstract base class for self-contained, in-process plugins.

    Plugins must inherit from this class and implement at least one hook method.
    Three hook registration patterns are supported:

    1. Convention-based: Name your method to match the hook type
    2. Decorator-based: Use @hook decorator with custom method names
    3. Custom hooks: Define new hook types with @hook decorator
    """

    def __init__(self, config: PluginConfig) -> None:
        """Initialize plugin with configuration."""

    @property
    def name(self) -> str:
        """Plugin name from configuration."""

    @property
    def priority(self) -> int:
        """Plugin execution priority (lower number = higher priority)."""

    @property
    def mode(self) -> PluginMode:
        """Plugin execution mode (enforce/enforce_ignore_error/permissive/disabled)."""

    @property
    def hooks(self) -> list[str]:
        """Hook points where plugin executes (discovered via introspection)."""

    @property
    def conditions(self) -> list[PluginCondition] | None:
        """Conditions for plugin execution (optional)."""

    # Optional lifecycle methods
    async def initialize(self) -> None:
        """Initialize plugin resources (called when plugin is loaded)."""

    async def shutdown(self) -> None:
        """Cleanup plugin resources (called on shutdown)."""

Hook Implementation Patterns:

Plugins implement hooks using one of three patterns - they do not need to implement all hooks, only the ones they need:

Pattern 1: Convention-Based (method name matches hook type)

class MyPlugin(Plugin):
    async def tool_pre_invoke(
        self,
        payload: ToolPreInvokePayload,
        context: PluginContext
    ) -> ToolPreInvokeResult:
        # Implementation
        pass

Pattern 2: Decorator-Based (custom method names)

from mcpgateway.plugins.framework.decorator import hook

class MyPlugin(Plugin):
    @hook(ToolHookType.TOOL_POST_INVOKE)
    async def my_custom_handler(
        self,
        payload: ToolPostInvokePayload,
        context: PluginContext
    ) -> ToolPostInvokeResult:
        # Implementation
        pass

Pattern 3: Custom Hooks (new hook types)

from mcpgateway.plugins.framework.decorator import hook

class MyPlugin(Plugin):
    @hook("email_pre_send", EmailPayload, EmailResult)
    async def validate_email(
        self,
        payload: EmailPayload,
        context: PluginContext
    ) -> EmailResult:
        # Implementation
        pass

See Plugin Development Guide for detailed examples and best practices

Plugin Manager

The Plugin Manager loads configured plugins and executes them at their designated hook points based on a plugin's priority.

class PluginManager:
    """Singleton plugin manager for lifecycle management"""

    def __init__(self, config: str = "", timeout: int = 30): ...

    @property
    def config(self) -> Config | None:
        """Plugin manager configuration"""

    @property
    def plugin_count(self) -> int:
        """Number of loaded plugins"""

    @property
    def initialized(self) -> bool:
        """Manager initialization status"""

    async def initialize(self) -> None:
        """Initialize manager and load plugins"""

    async def shutdown(self) -> None:
        """Shutdown all plugins and cleanup"""

    def get_plugin(self, name: str) -> Optional[Plugin]:
        """Get plugin by name"""

    # Unified hook invocation API
    async def invoke_hook(
        self,
        hook_type: str,
        payload: PluginPayload,
        global_context: GlobalContext,
        **kwargs
    ) -> tuple[PluginResult, PluginContextTable]:
        """
        Invoke a specific hook type with the given payload.

        This is the primary API for executing plugins at hook points.
        Plugins are executed in priority order with conditional filtering.

        Args:
            hook_type: String identifier for the hook (e.g., HttpHookType.HTTP_AUTH_RESOLVE_USER,
                      ToolHookType.TOOL_PRE_INVOKE, PromptHookType.PROMPT_PRE_FETCH)
            payload: Hook-specific payload (e.g., HttpAuthResolveUserPayload,
                    ToolPreInvokePayload, PromptPrehookPayload)
            global_context: Shared request context across all plugins
            **kwargs: Additional hook-specific parameters

        Returns:
            tuple[PluginResult, PluginContextTable]: Combined plugin result and context table
        """
        ...

Usage Example:

# Invoke HTTP authentication hook
result, contexts = await plugin_manager.invoke_hook(
    HttpHookType.HTTP_AUTH_RESOLVE_USER,
    payload=HttpAuthResolveUserPayload(
        credentials=credentials,
        headers=HttpHeaderPayload(headers),
        client_host=client_host,
    ),
    global_context=GlobalContext(
        request_id=request_id,
        server_id=None,
        tenant_id=None,
    )
)

# Invoke MCP protocol hook
result, contexts = await plugin_manager.invoke_hook(
    HookType.TOOL_PRE_INVOKE,
    payload=ToolPreInvokePayload(
        name=tool_name,
        args=tool_args,
    ),
    global_context=global_context
)

Plugin Registry

The plugin registry implements plugin instance management and discovery.

class PluginInstanceRegistry:
    """Registry for plugin instance management and discovery"""

    def register(self, plugin: Plugin) -> None:
        """Register a plugin instance"""

    def unregister(self, name: str) -> None:
        """Unregister a plugin by name"""

    def get_plugin(self, name: str) -> Optional[PluginRef]:
        """Get plugin reference by name"""

    def get_plugins_for_hook(self, hook_type: HookType) -> list[PluginRef]:
        """Get all plugins registered for a specific hook"""

    def get_all_plugins(self) -> list[PluginRef]:
        """Get all registered plugins"""

    @property
    def plugin_count(self) -> int:
        """Number of registered plugins"""

    async def shutdown(self) -> None:
        """Shutdown all registered plugins"""

Plugin Reference System

Plugin reference is used as UUID for plugin registration, discovery, and lifecycle management.

class PluginRef:
    """Plugin reference with UUID tracking for lifecycle management"""

    def __init__(self, plugin: Plugin):
        self._plugin = plugin
        self._uuid = uuid.uuid4()  # Unique instance identifier

    @property
    def plugin(self) -> Plugin:
        return self._plugin

    @property
    def uuid(self) -> str:
        return self._uuid.hex

Configuration Loading

The Configuration Loader provides utilities for loading configuration from file.

class ConfigLoader:
    """Configuration loading and validation"""

    @staticmethod
    def load_config(config_path: str) -> Config:
        """Load plugin configuration from YAML file"""

    @staticmethod
    def validate_config(config: Config) -> None:
        """Validate plugin configuration"""

    @staticmethod
    def merge_configs(base: Config, override: Config) -> Config:
        """Merge configuration files"""

Plugin Configuration Models

Below are the Pydantic models for the plugin configuration system.

class PluginConfig(BaseModel):
    """Plugin configuration schema"""
    name: str                                    # Required: Unique plugin name
    kind: str                                    # Required: Plugin class path or "external"
    description: Optional[str] = None            # Plugin description
    author: Optional[str] = None                 # Plugin author
    version: Optional[str] = None                # Plugin version
    hooks: Optional[list[HookType]] = None       # Hook points to register
    tags: Optional[list[str]] = None             # Searchable tags
    mode: PluginMode = PluginMode.ENFORCE        # Execution mode
    priority: Optional[int] = None               # Execution priority
    conditions: Optional[list[PluginCondition]] = None # Execution conditions
    config: Optional[dict[str, Any]] = None      # Plugin-specific settings
    mcp: Optional[MCPConfig] = None              # External MCP server configuration

class PluginCondition(BaseModel):
    server_ids: Optional[set[str]] = None        # Target server IDs
    tenant_ids: Optional[set[str]] = None        # Target tenant IDs
    tools: Optional[set[str]] = None             # Target tool names
    prompts: Optional[set[str]] = None           # Target prompt names
    resources: Optional[set[str]] = None         # Target resource URIs
    user_patterns: Optional[list[str]] = None    # User pattern matching
    content_types: Optional[list[str]] = None    # Content type filtering

class MCPConfig(BaseModel):
    """MCP configuration for external plugins"""
    proto: TransportType                     # STDIO, SSE, or STREAMABLEHTTP
    url: Optional[str] = None                # Service URL (for HTTP transports)
    uds: Optional[str] = None                # Unix domain socket path (Streamable HTTP)
    script: Optional[str] = None             # Script path (for STDIO transport)
    cmd: Optional[list[str]] = None          # Command + args (for STDIO transport)
    env: Optional[dict[str, str]] = None     # Environment overrides (for STDIO)
    cwd: Optional[str] = None                # Working directory (for STDIO)

class PluginMode(str, Enum):
    """Plugin execution modes"""
    ENFORCE = "enforce"              # Block requests that violate plugin rules
    ENFORCE_IGNORE_ERROR = "enforce_ignore_error"  # Enforce rules, ignore errors
    PERMISSIVE = "permissive"        # Log violations but allow continuation
    DISABLED = "disabled"            # Plugin loaded but not executed

class PromptHookType(str, Enum):
    """Prompt lifecycle hook points"""
    PROMPT_PRE_FETCH = "prompt_pre_fetch"     # Before prompt retrieval
    PROMPT_POST_FETCH = "prompt_post_fetch"   # After prompt rendering

class ToolHookType(str, Enum):
    """Tool invocation hook points"""
    TOOL_PRE_INVOKE = "tool_pre_invoke"       # Before tool execution
    TOOL_POST_INVOKE = "tool_post_invoke"     # After tool execution

class ResourceHookType(str, Enum):
    """Resource fetching hook points"""
    RESOURCE_PRE_FETCH = "resource_pre_fetch" # Before resource fetching
    RESOURCE_POST_FETCH = "resource_post_fetch" # After resource retrieval

class HttpHookType(str, Enum):
    """HTTP authentication and middleware hook points"""
    HTTP_PRE_REQUEST = "http_pre_request"              # Before authentication
    HTTP_AUTH_RESOLVE_USER = "http_auth_resolve_user"  # Custom authentication
    HTTP_AUTH_CHECK_PERMISSION = "http_auth_check_permission"  # Permission checking
    HTTP_POST_REQUEST = "http_post_request"            # After request completion

class AgentHookType(str, Enum):
    """Agent-to-Agent hook points"""
    AGENT_PRE_INVOKE = "agent_pre_invoke"     # Before agent invocation
    AGENT_POST_INVOKE = "agent_post_invoke"   # After agent completion

class TransportType(str, Enum):
    """Supported MCP transport protocols"""
    SSE = "sse"                        # Server-Sent Events
    HTTP = "http"                      # HTTP
    STDIO = "stdio"                    # Standard input/output
    STREAMABLEHTTP = "streamablehttp"  # HTTP with streaming support

Context Management

Plugin Context System

class GlobalContext(BaseModel):
    """Shared context across all plugins in a request"""
    request_id: str                  # Unique request identifier
    user: Optional[str] = None       # User making the request
    tenant_id: Optional[str] = None  # Tenant context
    server_id: Optional[str] = None  # Virtual server context

class PluginContext(GlobalContext):
    """Per-plugin context with state management"""
    state: dict[str, Any] = {}       # Cross-plugin shared state
    metadata: dict[str, Any] = {}    # Plugin execution metadata

    def get_state(self, key: str, default: Any = None) -> Any:
        """Get value from shared state"""
        return self.state.get(key, default)

    def set_state(self, key: str, value: Any) -> None:
        """Set value in shared state"""
        self.state[key] = value

Context Lifecycle Management

class PluginManager:
    # Context cleanup tracking
    _context_store: Dict[str, Tuple[PluginContextTable, float]] = {}
    _last_cleanup: float = 0

    async def _cleanup_old_contexts(self) -> None:
        """Remove contexts older than CONTEXT_MAX_AGE to prevent memory leaks"""
        current_time = time.time()

        if current_time - self._last_cleanup < CONTEXT_CLEANUP_INTERVAL:
            return

        # Find and remove expired contexts
        expired_keys = [
            key for key, (_, timestamp) in self._context_store.items()
            if current_time - timestamp > CONTEXT_MAX_AGE
        ]

        for key in expired_keys:
            del self._context_store[key]

Hook System

Hook Execution Flow

The hook execution flow implements a priority-based pipeline that processes MCP requests through multiple plugin layers before reaching core gateway logic. This architecture ensures predictable plugin execution order while enabling comprehensive request/response transformation and policy enforcement.

---
config:
  mirrorActors: false
---
sequenceDiagram
    participant Client
    participant Gateway
    participant PM as PluginManager
    participant P1 as Plugin 1 (Priority 10)
    participant P2 as Plugin 2 (Priority 20)
    participant Core as Core Logic

    Client->>Gateway: MCP Request
    Gateway->>PM: Execute Hook (pre hook, e.g., tool_pre_invoke)

    PM->>P1: Execute (higher priority)
    P1-->>PM: Result (continue=true, modified_payload)

    PM->>P2: Execute with modified payload
    P2-->>PM: Result (continue=true)

    PM-->>Gateway: Final Result

    alt Continue Processing
        Gateway->>Core: Execute Core Logic
        Core-->>Gateway: Response
        Gateway-->>Client: Success Response
    else Block Request
        Gateway-->>Client: Violation Response
    end

Execution Flow Breakdown

Phase 1: Request Reception & Hook Identification

1. Client Request: MCP client sends request (tool invocation, prompt fetch, resource access) to the gateway
2. Hook Selection: Gateway identifies the appropriate hook type based on the request (e.g., tool_pre_invoke for tool calls)
3. Plugin Manager Invocation: Gateway delegates hook execution to the Plugin Manager with request payload

Phase 2: Priority-Based Plugin Execution

4. Plugin Discovery: Plugin Manager retrieves all plugins registered for the specific hook type
5. Priority Sorting: Plugins are sorted in ascending priority order (lower numbers execute first)
6. Conditional Filtering: Plugins with conditions are filtered based on current request context (user, tenant, server, etc.)

Phase 3: Sequential Plugin Processing

7. First Plugin Execution: Highest priority plugin (P1, priority 10) executes with original payload
8. Result Evaluation: Plugin returns PluginResult indicating whether to continue processing
9. Payload Chain: If P1 modifies the payload, the modified version is passed to the next plugin
10. Second Plugin Execution: Next priority plugin (P2, priority 20) executes with potentially modified payload
11. Continue Chain: Process repeats for all remaining plugins in priority order

Phase 4: Flow Control Decision

12. Aggregated Result: Plugin Manager combines all plugin results and determines final action
13. Continue vs Block: Based on plugin results, request either continues to core logic or is blocked

Phase 5: Request Resolution

• Continue Path: If all plugins allow processing, request continues to core gateway logic

  • Core logic executes the actual MCP operation (tool invocation, prompt rendering, resource fetching)
  • Success response is returned to client

• Block Path: If any plugin blocks the request with a violation

  • Request processing stops immediately
  • Violation details are returned to client as an error response

Plugin Interaction Patterns

Payload Transformation Chain:

Original Payload → Plugin 1 → Modified Payload → Plugin 2 → Final Payload → Core Logic

Example Flow for Tool Pre-Invoke:

1. Client calls file_reader tool with path argument
2. Gateway triggers tool_pre_invoke hook
3. Security Plugin (Priority 10): Validates file path, blocks access to /etc/passwd
4. Sanitization Plugin (Priority 20): Never executes (request blocked)
5. Result: Client receives "Access Denied" error

Alternative Success Flow:

1. Client calls file_reader tool with path ./documents/report.txt
2. Security Plugin (Priority 10): Validates path, allows access, normalizes path
3. Sanitization Plugin (Priority 20): Adds read timeout, limits file size
4. Core Logic: Executes file reading with sanitized parameters
5. Result: Client receives file contents

Error Handling and Resilience

Plugin Error Isolation:

• Plugin execution errors don't crash other plugins or the gateway

• Failed plugins are logged and handled based on their execution mode:

  • Enforce Mode: Plugin errors block the request
  • Permissive Mode: Plugin errors are logged but request continues
  • Enforce Ignore Error Mode: Plugin violations block, but technical errors are ignored

Timeout Protection:

• Each plugin execution is wrapped with configurable timeouts (default 30 seconds)
• Timed-out plugins are treated as errors according to their execution mode
• External plugins may have longer timeout allowances due to network latency

Context Preservation:

• Plugin contexts are preserved across the execution chain
• State set by early plugins is available to later plugins
• Global context maintains request-level information throughout the flow

This execution model ensures predictable behavior, comprehensive security coverage, and operational resilience while maintaining the flexibility to implement complex policy enforcement and content transformation workflows.

Plugin Execution Priority

• Plugins execute in ascending priority order (lower numb

…(truncated)