Overview Freento MCP is a Magento 2 extension that implements the Model Context Protocol — an open standard for connecting AI assistants to external data sources. With this extension, you can:
Query orders, products, customers, and inventory using natural language Generate sales reports and analytics on the fly Monitor system health (PHP, MySQL, cache, search engine versions) Audit admin users and security settings
The MCP server acts as a secure bridge between AI assistants and your Magento installation, providing access to various store resources including the database, configuration, and other Magento subsystems.
Requirements Magento 2.4.x (Open Source or Commerce) PHP 8.1 or higher An MCP-compatible AI client (Claude Code, Claude Desktop, or ChatGPT with MCP plugin) Installation Via Composer (Recommended) composer require freento/module-mcp php bin/magento module:enable Freento_Mcp php bin/magento setup:upgrade php bin/magento cache:flush Manual Installation Download the module and extract to app/code/Freento/Mcp/ Enable the module: php bin/magento module:enable Freento_Mcp php bin/magento setup:upgrade php bin/magento cache:flush Verify Installation php bin/magento module:status Freento_Mcp Expected output: Module is enabled
Configuration Step 1: Create ACL Role In Magento Admin, go to System > Freento MCP > ACL Rules Click Add New Role Enter a name (e.g., "AI Assistant") Select which tools the role can access: Sales tools (orders, quotes, credit memos) Catalog tools (products, stock) Customer tools Admin tools System tools Save the role Step 2: Create OAuth Client Go to System > Freento MCP > AI MCP Clients Click Add New Client Enter a name (e.g., "Claude Code") Select the ACL Role created in Step 1 Save the client Copy the Client ID and Client Secret Step 3: Generate Access Token Open the OAuth Client you created Click Generate OTP — copy the one-time password (valid 24 hours) Click Generate Token — enter the OTP when prompted Copy the generated Access Token Claude Code Add to your project's .mcp.json:
{ "mcpServers": { "magento": { "type": "http", "url": "https://your-store.com/freento_mcp/index/index", "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" } } } } Then reconnect MCP in Claude Code:
/mcp Claude Desktop Edit your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):
{ "mcpServers": { "magento": { "type": "http", "url": "https://your-store.com/freento_mcp/index/index", "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" } } } } Restart Claude Desktop to apply changes.
ChatGPT and Other Web Clients For web-based AI tools that support OAuth 2.0:
Register your store's MCP endpoint: https://your-store.com/freento_mcp/index/index Enter the Client ID and Client Secret from Step 2 When prompted to authorize, enter the OTP generated from the OAuth Client page Complete the OAuth authorization flow Available Tools Each tool supports flexible filtering, sorting, and pagination. Combined with AI, these capabilities become virtually unlimited — the AI can execute multiple queries, cross-reference data, group and aggregate results, and provide intelligent analysis.
AI can:
Run multiple queries across different entities in one conversation Filter by any field using operators: eq, neq, in, like, gt, gte, lt, lte Sort and paginate results Aggregate with sum, count, avg, min, max Group by field or time period (day, month) Combine and analyze data from multiple sources Sales Tools Tool Description get_orders Query orders with filtering, pagination, and aggregation get_order_items Get order line items (products in orders) get_quotes Query shopping carts (active and abandoned) get_quote_items Get cart line items get_creditmemos Query credit memos Marketing Tools Tool Description get_cart_price_rules Query cart price rules get_coupons Query coupons Catalog Tools Tool Description get_products Query products with attribute filtering get_categories Query product categories get_product_prices Get product prices by customer group and website get_product_tier_prices Get tier price rules (quantity-based discounts) get_tax_rules Get tax rules and rates get_stock_single_stock Get inventory/stock levels Customer Tools Tool Description get_customers Query customer accounts Admin Tools Tool Description get_admins List admin users and their roles get_locked_admins Find locked admin accounts (failed login attempts) System Tools Tool Description get_system_versions Get Magento, PHP, MySQL, Redis, OpenSearch versions get_stores Get store hierarchy (websites, store groups, store views) Usage Examples Once configured, you can ask your AI assistant questions in natural language:
Orders & Sales "How many orders were placed last month?" "Show me the 10 most recent orders" "Find all orders over $500 that are still processing" "What's the total revenue by payment method this year?" "List orders for customer john@example.com" Products & Inventory "Show me out of stock products" "Find products with SKU starting with 'ABC'" "List products with less than 10 items in stock" "Get all configurable products updated this week" Customers "How many customers registered this month?" "Find customer with email jane@example.com" "List customers in the Wholesale group" System & Admin "What PHP version is running?" "Show me all admin users" "Are there any locked admin accounts?" "What search engine is configured?" Analytics & Reports "Revenue by month for the last 12 months" "Top 10 customers by total order value" "Average order value by payment method" "Order count by status" Advanced AI-Powered Analysis The real power comes from combining data with AI reasoning. Ask complex business questions and get actionable insights:
Customer Intelligence:
"Analyze my top 10 customers from the last 6 months. Who are they, what do they buy, and how can I increase sales?" The AI will retrieve the data and provide analysis like:
Mike Johnson — $4,250 total, 8 orders Profile: Professional drummer buying cymbals and drumsticks every 5-6 weeks
Recommendation: Set up auto-replenishment for drumsticks, offer early access to new cymbal arrivals, consider a "drummer's loyalty" discount tier.
Churn Prevention:
"Find customers who were active but haven't ordered in 90 days. What patterns do you see and how can I win them back?" Inventory Optimization:
"Analyze sales velocity vs current stock levels. What should I reorder and what's at risk of becoming dead stock?" Revenue Opportunities:
"What patterns exist in high-value orders? How can I get more customers to spend at that level?" Abandoned Cart Analysis:
"Look at abandoned carts from this week. What are people leaving behind and what might be causing it?" This transforms your store data into strategic business intelligence — insights that would typically require hours with spreadsheets or a dedicated analyst.
Filtering & Operators All list tools support powerful filtering via the filters parameter.
Filter Structure { "filters": { "field_name": { "operator": "value" } } } Available Operators Operator Description Example eq Equals {"status": {"eq": "processing"}} neq Not equals {"status": {"neq": "canceled"}} in In list {"status": {"in": ["processing", "complete"]}} nin Not in list {"status": {"nin": ["canceled", "closed"]}} like SQL LIKE pattern {"email": {"like": "%@gmail.com"}} nlike SQL NOT LIKE {"sku": {"nlike": "TEST%"}} gt Greater than {"grand_total": {"gt": 100}} gte Greater or equal {"qty": {"gte": 10}} lt Less than {"created_at": {"lt": "2024-01-01"}} lte Less or equal {"price": {"lte": 50}} Combining Filters Multiple filters are combined with AND logic:
{ "filters": { "status": {"in": ["processing", "pending"]}, "grand_total": {"gte": 100}, "created_at": {"gte": "2024-01-01"} } } Date Filtering Use YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format:
{ "filters": { "created_at": {"gte": "2024-01-01", "lt": "2024-02-01"} } } Aggregation & Analytics The get_orders tool supports aggregation for analytics:
Parameters Parameter Values Description function count, sum, avg, min, max Aggregation function field grand_total, total_qty_ordered, total_item_count Field to aggregate group_by status, month, day, customer_email, store_id, payment_method Grouping Examples Total order count:
{"function": "count"} Revenue by month:
{ "function": "sum", "field": "grand_total", "group_by": "month" } Average order value by payment method:
{ "function": "avg", "field": "grand_total", "group_by": "payment_method" } Top 10 customers by spending:
{ "function": "sum", "field": "grand_total", "group_by": "customer_email", "filters": { "status": {"nin": ["canceled", "closed"]} }, "limit": 10 } Troubleshooting Tools not appearing in AI assistant Verify the module is enabled:
php bin/magento module:status Freento_Mcp Flush Magento cache:
php bin/magento cache:flush Reconnect MCP in your AI client (e.g., /mcp in Claude Code)
"Authentication failed" error Verify your access token is correct Check the OAuth Client is enabled in Magento Admin Regenerate the token if it has expired "Access denied" error The ACL Role lacks required permissions. Edit the ACL Role in System > Freento MCP > ACL Rules and grant access to the necessary tools.
Connection timeout
Verify your Magento store is accessible from the internet
Check firewall rules allow incoming connections
For local development, use a tunnel service like ngrok
Test the endpoint manually
curl -X POST https://your-store.com/freento_mcp/index/index
-H "Content-Type: application/json"
-H "Authorization: Bearer YOUR_TOKEN"
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Security Best Practices Use HTTPS — Always use HTTPS in production to encrypt API communications
Minimal Permissions — Grant only the tools needed for your use case via ACL Roles
Separate Clients — Create separate OAuth Clients for different users/purposes
Regular Audits — Periodically review active clients and disable unused ones
Token Rotation — Regenerate access tokens periodically
Anonymity Mode — Enable anonymity mode in Stores > Configuration > Freento MCP > Privacy to hide PII fields (emails, names) from MCP tool responses. Since AI assistants connecting via MCP are third-party services, it is recommended to enable this mode to prevent customer personal data from being transmitted externally unless explicitly needed.
Token Security Never commit tokens to version control Use environment variables or secure secret management Rotate tokens periodically Revoke tokens immediately if compromised Support Contact: https://freento.com/contact