Moqui MCP: Intelligent Automation for Enterprise Business

Transform Your ERP into an AI-Powered Command Center

Moqui MCP bridges the gap between cutting-edge AI and enterprise operations, enabling intelligent agents to interact directly with your business systems through the Model Context Protocol (MCP). Built on the robust Moqui Framework, this solution brings autonomous decision-making to every corner of your organization.

Enterprise-Grade Security: This powerful platform requires careful access control and proper authorization. Built on Moqui's proven security model, it ensures AI capabilities are deployed responsibly with full auditability.

---

🚀 Transform Your Business Operations

Intelligent Automation at Scale

• Smart Procurement: AI agents that analyze inventory, predict demand, and optimize purchasing decisions
• Dynamic Market Response: Real-time pricing adjustments based on supply chain data and market conditions
• Workforce Optimization: Intelligent scheduling and resource allocation powered by financial modeling
• Supply Chain Excellence: Automated coordination across global logistics networks

Data-Driven Decision Making

• Strategic Insights: AI-powered analysis of real sales trends and operational metrics
• Predictive Analytics: Financial forecasting grounded in actual business performance
• Proactive Risk Management: Continuous monitoring for anomalies, opportunities, and optimization
• Automated Compliance: Intelligent enforcement of business rules and regulatory requirements

The Future of Enterprise AI

• Collaborative AI Teams: Coordinated agents across Sales, Operations, Finance, and more
• Event-Driven Intelligence: Automated responses through Moqui's ECA/SECA framework
• Inter-Enterprise Coordination: AI agents that communicate and transact across organizational boundaries
• Digital Twin Simulations: Test and optimize strategies in a live business environment

Harness the Power of Agentic Architecture: Enterprise Resource Planning systems are naturally designed for role-based operations—HR, Sales, Production, Accounting each with distinct responsibilities and workflows. Moqui MCP transforms this organizational structure into an intelligent framework where AI agents assume authentic business personas, collaborate within established processes, and make decisions with real accountability. Your corporate hierarchy becomes the foundation for scalable AI automation.

From passive data systems to active business partners—AI that doesn't just analyze, but acts.

---

Overview

Moqui MCP creates a seamless bridge between AI assistants and your enterprise systems, transforming how intelligent agents interact with business operations. By implementing the Model Context Protocol (MCP), we've unlocked direct, secure access to Moqui's comprehensive service layer and entity model—giving AI the ability to not just read data, but to execute real business processes.

What This Means for You

Imagine AI that can:

• Execute Business Logic: Create orders, process invoices, manage inventory—all through natural conversation
• Query Any Data: Access your complete entity model with intelligent schema discovery
• Work Securely: Every action respects Moqui's battle-tested authorization system
• Scale Naturally: From simple queries to complex multi-step business workflows

Two Powerful Interaction Patterns

1. Service Tools: Business Operations as AI Functions

Moqui services become callable tools for AI agents. When you expose mantle.order.OrderServices.create#Order, the AI receives a complete JSON Schema definition including all parameters, types, and constraints. The agent can then create orders just like your application code does—with full validation, security checks, and business rule enforcement.

Example: An AI agent can analyze inventory levels, identify low stock items, find the best suppliers, and automatically generate purchase orders—all by calling exposed Moqui services.

2. Entity Resources: Your Data Model, Discoverable

Every entity in your Moqui system becomes an MCP resource. AI agents can:

• Discover what entities exist (resources/list)
• Learn entity schemas—fields, types, relationships (resources/read)
• Query data using Moqui's powerful entity engine
• Understand your business domain model automatically

Example: Ask "What customer fields are available?" and the AI reads the mantle.party.Party and mantle.party.Person schemas to understand your customer data structure.

The Result: AI agents that understand your business domain and can operate within it—like hiring an infinitely patient, perfectly compliant employee who never needs training.

---

Architecture & Implementation

Core Components

MoquiMcpServlet

The protocol gateway—handles JSON-RPC 2.0 communication between MCP clients (like Claude Desktop) and your Moqui instance. Manages WebSocket connections, session lifecycle, and message routing with full integration into Moqui's Visit tracking system.

McpServices

The intelligence layer that makes everything work:

• mcp#Initialize: Negotiates MCP protocol capabilities, establishes secure sessions
• mcp#ToolList: Dynamically discovers authorized services and generates tool definitions with complete JSON schemas. Includes smart filtering (like the forClaude parameter) to handle client-specific constraints
• mcp#ResourceList: Exposes your entity model as discoverable resources
• mcp#ResourceRead: Returns detailed entity schemas including fields, relationships, and indexes
• mcp#CallTool: Routes tool calls to actual Moqui services, handling parameter transformation and result packaging

Security Integration

This is where Moqui's artifact authorization system shines. Every service call, every entity query goes through the same security checks your applications use. If a user can't access mantle.account.PaymentServices through your UI, they can't access it through MCP either. Zero compromise on security.

Schema Intelligence

Moqui services can have complex parameter structures—nested Maps, Lists of objects, conditional requirements. Our schema generator recursively analyzes service definitions to produce accurate JSON Schema, including:

• Proper type mapping (Moqui types → JSON Schema types)
• Required vs optional parameters
• Nested object structures
• Array item types
• Enum values for status fields

Key Features Explained

🔧 Automatic Service Discovery Point the system at your component, and it finds all services the current user can access. No manual API definitions, no maintenance burden. As you add services, they automatically become available to AI agents (subject to authorization).

📚 Entity-as-Resource Pattern Following MCP's resource model, entities aren't just data—they're discoverable knowledge. AI agents can explore your schema, understand relationships, and learn your business domain organically.

🎯 Claude Desktop Ready Some AI clients (looking at you, Claude) have tool name length limits. The forClaude parameter intelligently filters the tool list to stay within constraints while maximizing available functionality.

🔒 Security-First Design Built on Moqui's proven artifact authorization system. Every exposed service, every entity query, every tool call is subject to the same security rules that protect your web applications and APIs.

⚡ Session Continuity MCP sessions integrate with Moqui's Visit system, maintaining context across multiple interactions. The AI "remembers" what it's working on, just like a user session in your web app.

Why This Architecture Works

Moqui's service-oriented architecture is uniquely suited for AI integration:

1. Self-Documenting: Service definitions include parameter metadata that generates perfect API schemas
2. Transaction-Safe: Every service call runs in Moqui's transaction management system
3. Event-Driven: SECA rules fire on AI actions just like user actions—full business logic preservation
4. Multi-Tenant Ready: Organization filtering and data isolation work automatically
5. Auditable: Every AI action flows through Moqui's audit logging system

---

Getting Started

Quick Setup

1. Clone into your Moqui runtime:

   cd runtime/component
   git clone https://github.com/yourusername/moqui-mcp.git
   

2. Configure your MCP client:

   For Claude Desktop (requires mcp-remote as Claude only supports stdio mode):

   Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "moqui-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@latest",
           "http://localhost:8080/mcp/",
           "--allow-http",
           "--header",
           "Authorization:Basic ${AUTH_TOKEN}",
           "--header",
           "Content-Type:application/json",
           "--header",
           "Accept:application/json"
         ],
         "env": {
           "AUTH_TOKEN": "<your-base64-token>"
         }
       }
     }
   }
   

   Note: The AUTH_TOKEN is the Base64 encoding of username:password. Generate yours with:

   echo -n "your-username:your-password" | base64
   

   For GitHub Copilot:

   Add to your Copilot MCP settings:

   {
     "servers": {
       "moqui-mcp": {
         "type": "http",
         "url": "http://localhost:8080/mcp/",
         "requestInit": {
           "headers": {
             "Authorization": "Basic <your-base64-token>"
           }
         }
       }
     }
   }
   

   Replace <your-base64-token> with your Base64-encoded username:password.

3. Start exploring:

   • Ask AI to list available tools: "What services can you access?"
   • Query your data model: "Show me the Order entity schema"
   • Execute business operations: "Create a test order for customer ACME"

Testing & Development

The component includes a comprehensive test suite in test/. Contributions are welcome! If you're building new features or fixing bugs, please add tests.

---

Real-World Use Cases

Intelligent Customer Service

AI agents can look up orders, check shipment status, process returns, and update customer information—all through natural language while respecting your security policies.

Automated Procurement

Agents monitor inventory levels, analyze supplier performance, and generate purchase orders when stock falls below thresholds—operating within your defined business rules.

Financial Operations

From invoice processing to payment reconciliation, AI can handle routine financial tasks while maintaining full audit trails and compliance requirements.

Data Analysis & Reporting

Instead of building custom dashboards, let AI query your entity model directly to answer business questions: "Which products had the highest returns last quarter?"

---

License

This project is released into the public domain under CC0 1.0 Universal plus a Grant of Patent License, maintaining consistency with the Moqui Framework licensing philosophy. Use it freely, modify it as needed, build commercial products with it—no strings attached.

Related Projects & Resources

Essential Reading

• Moqui Framework - The foundation this builds upon. If you're new to Moqui, start here.
• MCP Specification - Understand the protocol that enables AI integration
• Mantle Business Artifacts - The business service layer that powers most MCP tools

Complementary Projects

• MarbleERP - Full ERP component for Moqui, p