MCP Server - authenticated Model Context Protocol gateway for ProcessWire

[maximus]

Hi everyone,

I’m releasing MCP Server, a ProcessWire module that connects Codex and other Model Context Protocol clients to ProcessWire through one authenticated Streamable HTTP endpoint.

Installed modules explicitly opt in as MCP providers and expose only bounded, documented tools. Each provider keeps ownership of its permissions, validation and business rules, while MCP Server handles transport, authentication, scopes, rate limits, tool discovery and audit history.

Main features:

• Official PHP MCP SDK and Streamable HTTP transport
• Separate revocable credentials for every client
• One-time token disclosure with salted, installation-protected hashes
• Hierarchical read, draft, publish and admin scopes
• Installation-specific tool namespace
• Closed JSON Schema validation and safety annotations
• Per-client rate limiting and Host, Origin and body-size protection
• Audit records without storing raw tool arguments
• Admin workspaces for clients, providers, tools and audit history
• Optional bounded JSON CLI
• Endpoint disabled by default
• No arbitrary PHP, SQL, shell, filesystem or generic content API

Initial integrations: Tickets, Ichiban, Liora, Olivia, Relay, Vox, Verk, Folio, Resend.

Requirements: ProcessWire 3.0.200+, PHP 8.2+, HTTPS for production and a strong $config->userAuthSalt.

Install the complete module in /site/modules/McpServer/, refresh modules, open Setup → MCP Server, configure the endpoint boundary, create a least-privilege client and review all discovered tools before enabling remote access.

GitHub, installation guide and API documentation:
https://github.com/mxmsmnv/McpServer

Feedback on the provider contract, MCP client compatibility and security model is very welcome.

[maximus]

For module authors, adding MCP support does not require implementing the transport or authentication layer.

An existing module only needs to opt in and expose bounded tools.

First, add the provider flag to the module metadata:

public static function getModuleInfo(): array {
    return [
        'title' => 'My Module',
        'version' => 100,
        'mcpProvider' => true,
    ];
}

Then add the provider contract:

public function mcpProviderInfo(): array {
    return [
        'name' => 'my-module',
        'title' => 'My Module',
        'version' => (string) self::getModuleInfo()['version'],
    ];
}

public function mcpTools(): array {
    return [[
        'name' => 'my_module_status',
        'title' => 'My Module status',
        'description' => 'Return the current module readiness state.',
        'handler' => [$this, 'mcpModuleStatus'],

        'scope' => 'read',
        'read_only' => true,
        'destructive' => false,
        'idempotent' => true,
        'open_world' => false,

        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'include_details' => [
                    'type' => 'boolean',
                ],
            ],
            'additionalProperties' => false,
        ],
    ]];
}

public function mcpModuleStatus(bool $include_details = false): array {
    $result = [
        'ready' => true,
        'module' => 'my-module',
    ];

    if($include_details) {
        $result['version'] = (string) self::getModuleInfo()['version'];
    }

    return $result;
}

After refreshing the ProcessWire module cache, MCP Server discovers the provider automatically. The exposed tool receives the configured installation namespace, so my_module_status may become example_my_module_status.

A few rules are important:

• Schema property names must match the PHP handler parameters.
• Inputs and result sets must always be bounded.
• The owning module remains responsible for permissions and validation.
• Use read, draft, publish or admin as the tool scope.
• Describe read_only, destructive, idempotent and open_world accurately.
• Write tools should require explicit confirmation and return stable identifiers.
• Expected domain failures can be reported with WireException.
• Never expose generic PHP, SQL, shell or filesystem access.

The complete provider contract is documented here:
https://github.com/mxmsmnv/McpServer/blob/main/API.md