Essentials MCP

Enable AI agents and assistants to integrate seamlessly with Composable Commerce through standardized function calling.

With Essentials MCP, you can enable AI agents to perform operations such as reading product information, managing carts and orders, handling customer data, and executing various commerce workflows through natural language interactions.

Essentials MCP supports both read-only operations for safe data access and full CRUD operations for comprehensive commerce management.

Placeholder values

Example code and commands in this guide uses the following placeholder values. You should replace these placeholders with the following values.

If you do not have an API Client, follow our Get your API Client guide.
PlaceholderReplace withFrom
{PROJECT_KEY}project_keyyour API Client
{CLIENT_ID}client_idyour API Client
{CLIENT_SECRET}secretyour API Client
{AUTH_URL}your Authorization URLRequest an access token using the Composable Commerce OAuth 2.0 service
{API_URL}your API URLHosts

Installation

Use the following commands to run Essentials MCP using npx:

Set up all available toolsbash
npx -y @commercetools/mcp-essentials \
  --tools=all \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL
Set up all read-only toolsbash
npx -y @commercetools/mcp-essentials \
  --tools=all.read \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL
Configure a specific tool (products.read and products.create)bash
# To set up specific tools
npx -y @commercetools/mcp-essentials \
  --tools=products.read,products.create \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL

Use with Claude Desktop

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL"
      ]
    }
  }
}
To use only read-only tools, replace "--tools=all" with "--tools=all.read".

Available tools

Special Tool Options

ToolDescription
allEnable all available tools (read, create, and update operations)
all.readEnable all read-only tools

Individual Tools

ToolDescription
bulk.createCreate entities in bulk
bulk.updateUpdate entities in bulk
business-unit.createCreate business unit
business-unit.readRead business unit
business-unit.updateUpdate business unit
cart.createCreate cart
cart.readRead cart information
cart.updateUpdate cart information
cart-discount.createCreate cart discount
cart-discount.readRead cart discount
cart-discount.updateUpdate cart discount
category.createCreate category
category.readRead category information
category.updateUpdate category
channel.createCreate channel
channel.readRead channel information
channel.updateUpdate channel information
customer.createCreate customer
customer.readRead customer information
customer.updateUpdate customer information
customer-group.createCreate customer group
customer-group.readRead customer group
customer-group.updateUpdate customer group
discount-code.createCreate discount code
discount-code.readRead discount code information
discount-code.updateUpdate discount code information
inventory.createCreate inventory
inventory.readRead inventory information
inventory.updateUpdate inventory information
order.createCreate order (from cart, quote, import)
order.readRead order information
order.updateUpdate order information
product-discount.createCreate product discount
product-discount.readRead product discount
product-discount.updateUpdate product discount
product-search.readSearch products
product-selection.createCreate product selection
product-selection.readRead product selection
product-selection.updateUpdate product selection
product-type.createCreate product type
product-type.readRead product type
product-type.updateUpdate product type
products.createCreate product information
products.readRead product information
products.updateUpdate product information
project.readRead project information
quote.createCreate quote
quote.readRead quote information
quote.updateUpdate quote information
quote-request.createCreate quote request
quote-request.readRead quote request
quote-request.updateUpdate quote request
staged-quote.createCreate staged quote
staged-quote.readRead staged quote
staged-quote.updateUpdate staged quote
standalone-price.createCreate standalone price
standalone-price.readRead standalone price
standalone-price.updateUpdate standalone price
store.createCreate store
store.readRead store
store.updateUpdate store

Agent Essentials

Agent Essentials enables agent frameworks to integrate with APIs through function calling. Agent Essentials is not exhaustive of the entire commercetools API, and uses the TypeScript SDK.

Agent Essentials requires Node 18 (or later) and can be installed using the following command:

npm install @commercetools/agent-essentials

Usage

Agent Essentials must be configured to use API Client credentials. The API Client must have necessary scopes to perform respective actions. For example, if you configure products: { read: true }, your API client must have the view_products scope.
The following examples use environment variables to load the credentials, which you can save after creating your API Client.
Additionally, you can define the actions available using the toolkit in configuration.
import { CommercetoolsAgentToolkit } from '@commercetools/agent-essentials/langchain';

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Tools

The toolkit works with LangChain and AI SDK by Vercel and can be passed as a list of tools.

import { AgentExecutor, createStructuredChatAgent } from 'langchain/agents';

const tools = commercetoolsAgentToolkit.getTools();

const agent = await createStructuredChatAgent({
  llm,
  tools,
  prompt,
});

const agentExecutor = new AgentExecutor({
  agent,
  tools,
});

Set up an MCP server

The following code example demonstrates how to set up your own MCP server.

import { CommercetoolsAgentToolkit } from '@commercetools/agent-essentials/modelcontextprotocol';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    actions: {
      products: {
        read: true,
      },
      cart: {
        read: true,
        create: true,
        update: true,
      },
    },
  },
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('My custom commercetools MCP Server running on stdio');
}

main().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});

getTools()

The getTools() method returns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:
const tools = commercetoolsAgentToolkit.getTools();
Do not commit linked packages in package.json to your repository when doing local development.