mcf-plugin

Create a gateway plugin for: $ARGUMENTS

Plugin Type Decision

Ask the user unless obvious from context:

• Native (in-process) — Python class extending Plugin. Runs inside the gateway process. Best for transforms, filters, validators, and anything needing low latency.
• External (MCP server) — Separate MCP server connected via Streamable HTTP, STDIO, or UDS. Best for integrating third-party services, policies requiring isolation, or non-Python implementations.

Hook Types

Six production hooks — plugins override only the hooks they need:

Hook	When	Typical Use
prompt_pre_fetch	Before retrieving a prompt	Validate/transform args, mask PII, block
prompt_post_fetch	After rendering a prompt	Filter/sanitize content, add metadata
tool_pre_invoke	Before executing a tool	Auth/validation, policy checks, arg mutation, block
tool_post_invoke	After tool returns	Redact outputs, transform result, audit
resource_pre_fetch	Before fetching a URI	Protocol/domain checks, metadata injection, block
resource_post_fetch	After content fetched	Size checks, redaction, content transformation

Native Plugin

Step 1: Create plugin directory

plugins/<plugin_name>/
  <plugin_name>.py    # Plugin class
  __init__.py          # empty

Convention: 42 built-in plugins exist under plugins/. Follow the same flat structure.

Step 2: Write the plugin class

# -*- coding: utf-8 -*-
"""<Plugin description>."""
from mcpgateway.plugins.framework.base import Plugin
from mcpgateway.plugins.framework.models import (
    PluginConfig,
    PluginContext,
    PluginViolation,
    ToolPreInvokePayload,
    ToolPreInvokeResult,
)


class MyPlugin(Plugin):
    """<Description of what this plugin does>."""

    async def tool_pre_invoke(
        self, payload: ToolPreInvokePayload, context: PluginContext
    ) -> ToolPreInvokeResult:
        # Access plugin-specific config
        threshold = self.config.config.get("threshold", 100)

        # Check condition
        if some_violation_detected(payload):
            return ToolPreInvokeResult(
                continue_processing=False,
                violation=PluginViolation(
                    reason="Policy violation",
                    description="Detailed explanation",
                    code="MY_PLUGIN_VIOLATION",
                    details={"matched": True},
                ),
            )

        # Pass through (optionally modify payload)
        return ToolPreInvokeResult(
            continue_processing=True,
            modified_payload=payload,
            metadata={"checked_by": "my_plugin"},
        )