Freento MCP for Magento 2 — User Guide

Connect your Magento 2 store to AI assistants like Claude and ChatGPT using the Model Context Protocol (MCP).

Table of Contents

• Overview
• Requirements
• Installation
• Configuration
  • Claude Code
  • Claude Desktop
  • ChatGPT
• Available Tools
• Usage Examples
• Filtering & Operators
• Aggregation & Analytics
• Troubleshooting
• Security

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

How it works:

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AI Assistant   │  HTTP   │  Freento MCP    │         │   Magento 2 /   │
│  (Claude/GPT)   │ ◄─────► │  Server         │ ◄─────► │Server Resources │
└─────────────────┘ JSON-RPC└─────────────────┘         └─────────────────┘

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

1. Download the module and extract to app/code/Freento/Mcp/
2. 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

1. In Magento Admin, go to System > Freento MCP > ACL Rules
2. Click Add New Role
3. Enter a name (e.g., "AI Assistant")
4. Select which tools the role can access:
   • Sales tools (orders, quotes, credit memos)
   • Catalog tools (products, stock)
   • Customer tools
   • Admin tools
   • System tools
5. Save the role

Step 2: Create OAuth Client

1. Go to System > Freento MCP > AI MCP Clients
2. Click Add New Client
3. Enter a name (e.g., "Claude Code")
4. Select the ACL Role created in Step 1
5. Save the client
6. Copy the Client ID and Client Secret

Step 3: Generate Access Token

1. Open the OAuth Client you created
2. Click Generate OTP — copy the one-time password (valid 24 hours)
3. Click Generate Token — enter the OTP when prompted
4. 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:

1. Register your store's MCP endpoint: https://your-store.com/freento_mcp/index/index
2. Enter the Client ID and Client Secret from Step 2
3. When prompted to authorize, enter the OTP generated from the OAuth Client page
4. 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

1. Verify the module is enabled:

   php bin/magento module:status Freento_Mcp
   

2. Flush Magento cache:

   php bin/magento cache:flush
   

3. 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

1. Use HTTPS — Always use HTTPS in production to encrypt API communications

2. Minimal Permissions — Grant only the tools needed for your use case via ACL Roles

3. Separate Clients — Create separate OAuth Clients for different users/purposes

4. Regular Audits — Periodically review active clients and disable unused ones

5. Token Rotation — Regenerate access tokens periodically

6. 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

License

MIT License — see LICENSE for details.