Reference: Model Context Protocol (MCP) Architecture

This document describes how MCP servers are implemented, registered, operated, and extended in the AIOHM platform.

Overview

Model Context Protocol (MCP) is a standardized communication layer that allows AI agents to discover and interact with external tools and services. In the AIOHM platform, MCP is the bridge that enables AI agents within workflows to perform complex, real-world tasks like publishing to WordPress, analyzing SEO, or managing marketing campaigns.

Core Concepts

• MCP Server: A standalone application (often a Node.js process) that exposes a set of capabilities. Each server is specialized for a specific service (e.g., WordPress, Mautic).
• MCP Tool: A specific function or action exposed by an MCP Server (e.g., wordpress_create_post, mautic_create_contact).
• Integration: MCP Servers are registered in the AIOHM database (mcp_servers table) and associated with tenants. Once registered and enabled, they become available as nodes in the Workflow Builder.

---

Available MCP Servers

The platform can run both local MCP servers and remote MCP endpoints (via a local adapter process).

Server	Description	Implementation
WordPress MCP	WordPress site/content operations	Local Node.js server
Mautic MCP Server	Marketing automation operations	Local Node.js server
SEO MCP Server	SEO analysis and optimization tools	Local Node.js server
KnowledgeBase MCP	Internal knowledge/docs access	Laravel server
Boost MCP	Laravel boost/introspection tools	Laravel server
Facebook MCP Server	Facebook/Meta operations	Local Node.js server
Postiz MCP Server	Social publishing through Postiz	Local Node.js or external npm server
Stripe MCP Server	Official Stripe MCP endpoint via adapter	npx mcp-remote https://mcp.stripe.com

---

Usage in Workflows

You can use any enabled MCP Server as a node within the Workflow Builder.

Adding an MCP Server Node

1. In the Workflow Builder, click "Add Node".
2. Select the "MCP Server" button (purple).
3. Choose the desired server (e.g., "WordPress MCP") from the list.

Configuring an MCP Server Node

1. Click the new MCP node on the canvas to open the Node Editor.
2. Node Name: Give the node a descriptive label (e.g., "Publish Article to Blog").
3. Server Configuration: In the textarea, provide plain-English instructions for the AI agent on how to use the server (e.g., which tool to use and with what data).

---

For Developers: Server Management & Development

This section covers the technical details of how MCP servers are organized and managed in the codebase.

Directory Structure

MCP servers are organized by type. For example:

• PHP Servers: app/Domains/AI/MCP/Servers/Laravel/
• Node.js Servers: app/Domains/AI/MCP/Servers/NodeJS/

Server Types

1. Laravel Servers: Built directly into the main Laravel application. Registered and booted via service providers and routes/ai.php.

2. Node.js Servers: Custom-built, standalone Node.js/TypeScript applications. Require npm install and npm run build in their server folder. Managed and invoked by AIOHM with server config in mcp_servers.

3. Remote MCP Endpoints: Hosted MCP services reachable via HTTPS (for example Stripe). Connected through a local stdio adapter command (mcp-remote) so they fit the same execution pipeline.

Management Commands

• Tenant-aware list: php artisan mcp:test list --tenant=<tenant_id>
• Tenant-aware stats: php artisan mcp:test stats --tenant=<tenant_id>
• Start all for tenant: php artisan mcp:test start-all --tenant=<tenant_id>
• Stop all for tenant: php artisan mcp:test stop-all --tenant=<tenant_id>
• Dry-run path cleanup: php artisan mcp:fix-paths --dry-run
• Apply path cleanup: php artisan mcp:fix-paths
• Deprecated cleanup dry-run: php artisan mcp:clean-deprecated
• Deprecated cleanup apply: php artisan mcp:clean-deprecated --apply
• Admin panel: /mcp in Filament for runtime control and settings.

Adding New Servers

1. Implement or choose server type. For Laravel: add a server class under app/Domains/AI/MCP/Servers/Laravel and register via Mcp::web / Mcp::local. For Node.js: add a server under app/Domains/AI/MCP/Servers/NodeJS/<server-name>/, with build artifact at build/index.js. For hosted endpoint: define a local adapter command (npx -y mcp-remote <endpoint-url>).

2. Seed registration. Add server definition to database/seeders/MCPServersSeeder.php (global and/or per-tenant block).

3. Credential wiring. Add credential resolution in App\Domains\AI\Services\MCPServerManager::prepareEnvironmentVariables() when server-specific secrets are required.

4. Tenant assignment. Ensure server exists with the target tenant_id and enabled flag set intentionally.

5. Validate. Run php artisan mcp:test list --tenant=<tenant_id> and php artisan mcp:test start-all --tenant=<tenant_id>.

Stripe MCP Notes

• Official endpoint: https://mcp.stripe.com
• Adapter command pattern: npx -y mcp-remote https://mcp.stripe.com
• Auth model: OAuth at Stripe MCP endpoint
• Recommended default in AIOHM: register as disabled, then enable per tenant when payment workflows are needed