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:

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

Marketing Tools

Catalog Tools

Customer Tools

Admin Tools

System Tools

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

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

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.