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

[MrSnoozles]

Hi @maximus

From the module description I don't understand what the MCP server does. Is it used to get information? Can it be used to modify pages? Can it edit fields / templates?

It sounds like it has a lot of cool technical features, but when should I install this module? And how does it compare to AgentTools from Ryan?
 

Edited August 27 by MrSnoozles

[maximus]

Here’s a more concrete example based on an integration I’m working on for Mercato, a ProcessWire-native commerce module.

Mercato already has internal services for orders, payments, inventory, fulfilment, shipping labels, tracking, refunds and transactional email. I’m planning to expose selected Mercato operations through an McpServer provider, such as:

• mercato.get_order
• mercato.list_orders_to_fulfil
• mercato.verify_payment
• mercato.create_shipment
• mercato.purchase_shipping_label
• mercato.update_tracking
• mercato.send_order_email

Any MCP-compatible bot, Codex instance or automation platform such as n8n could then operate the store through these tools.

For example, when a paid order appears, an automation could verify the payment with the remote provider, check variant inventory, create the shipment, purchase a shipping label, save the tracking information, advance fulfilment and notify the customer. If the payment, stock or shipping data does not match, it could stop the workflow and report the exception to a human instead of silently changing the order.

The important distinction is that McpServer is not the workflow engine itself. The bot, agent or n8n controls the sequence. McpServer provides the authenticated, scoped and audited capability layer, while Mercato performs the actual business logic.

It also does not have to expose generic operations such as “edit any page” or “modify any template”. A provider can expose only narrowly defined business actions. Each client can have its own credentials and scopes, so one integration might only read orders, another may fulfil them, while refunds or payment reconciliation remain separately protected and may require explicit confirmation.

That is how I see the difference from AgentTools:

• AgentTools is primarily for trusted local development and site engineering. Its CLI/Engineer can work broadly with ProcessWire structure and code, while its current MCP tools are read-only.
• McpServer is for controlled remote operation of an already deployed application: authenticated HTTP access, per-client scopes, rate limits and audit logs, with each module deciding exactly what external agents are allowed to read or change.

So yes, McpServer can be used both to retrieve information and to modify data—but only through explicit operations exposed by installed providers. It does not automatically give an AI unrestricted access to ProcessWire pages, fields or templates.