Essentials MCP

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

Essentials MCP enables AI frameworks, including Claude Desktop, LangChain, and AI SDK by Vercel, to access and interact with Composable Commerce APIs using natural language.

With Essentials MCP, agents can retrieve product information, manage carts and orders, handle customer data, and execute other Composable Commerce workflows. The toolkit supports both read-only access for safe operations and full CRUD functionality for advanced use cases.

Placeholder values

This guide uses the following placeholders in examples. You should replace these placeholders with the following values.

If you do not have an API Client, follow our Get your API Client guide.

Placeholder	Replace with	From
`{PROJECT_KEY}`	project_key	your API Client
`{CLIENT_ID}`	client_id	your API Client
`{CLIENT_SECRET}`	secret	your API Client
`{ACCESS_TOKEN}`	access_token	an existing access token (when using `auth_token` authentication type)
`{AUTH_URL}`	your Authorization URL	Request an access token using the Composable Commerce OAuth 2.0 service
`{API_URL}`	your API URL	Hosts

Authentication Types

Essentials MCP supports two authentication types:

client_credentials: uses client ID and client secret to obtain an access token.
auth_token: uses an existing access token.

Choose the authentication type that best fits your use case and provide the corresponding credentials.

The following examples use client_credentials authentication. You can alternatively use auth_token authentication by:

Setting --authType=auth_token (or type: 'auth_token' in TypeScript)
Replacing --clientId and --clientSecret with --accessToken=ACCESS_TOKEN

Setup STDIO Transport MCP Server

Installation

To run Essentials MCP using npx, use one of the following commands depending on the tools you need.

Set up all available toolsbash

npx -y @commercetools/mcp-essentials \
  --tools=all \
  --authType=client_credentials \
  --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 \
  --authType=client_credentials \
  --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 \
  --authType=client_credentials \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL

Using auth_token authentication

Set up all available tools with auth_tokenbash

npx -y @commercetools/mcp-essentials \
  --tools=all \
  --authType=auth_token \
  --accessToken=ACCESS_TOKEN \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL

Use with Claude Desktop

To use Essentials MCP with Claude Desktop, add the following to your claude_desktop_config.json. For setup instructions, see the For Claude Desktop Users quickstart guide.

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--isAdmin=true",
        "--authType=client_credentials",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL"
      ]
    }
  }
}

This example uses the --isAdmin=true flag, which provides full access to all commercetools resources, settings, and operations. This is useful for development and testing purposes, but should be used with caution in production environments. If not required, use --isAdmin=false to restrict access to only the tools specified in the --tools option.

To use only read-only tools, replace "--tools=all" with "--tools=all.read".

Setup Streamable HTTP Transport MCP Server

The Essentials MCP server, in addition to local STDIO server, also supports Streamable HTTP transport.

Installation

To be able to run Essentials MCP server in remote mode, use the following command:

Set up all available tools for Streamable HTTP serverbash

npx -y @commercetools/mcp-essentials \
  --tools=all \
  --authType=client_credentials \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL \
  --remote=true \
  --stateless=true \
  --port=8888

See Available tools for a list of values for tools.

Use with Claude Desktop

At this point, Essentials MCP server is running on the specified port (8888). Now you can configure Claude Desktop with the following:

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8888/mcp"]
    }
  }
}

Ensure you have mcp-remote installed on your machine.

Available tools

Special Tool Options

Tool	Description
`all`	Enable all available tools, including read, create, and update operations.
`all.read`	Enable all read-only tools.

Individual Tools

Tool	Description
`bulk.create`	Create entities in bulk
`bulk.update`	Update entities in bulk
`business-unit.create`	Create business unit
`business-unit.read`	Read business unit
`business-unit.update`	Update business unit
`cart.create`	Create cart
`cart.read`	Read cart information
`cart.update`	Update cart information
`cart-discount.create`	Create cart discount
`cart-discount.read`	Read cart discount
`cart-discount.update`	Update cart discount
`category.create`	Create category
`category.read`	Read category information
`category.update`	Update category
`channel.create`	Create channel
`channel.read`	Read channel information
`channel.update`	Update channel information
`customer.create`	Create customer
`customer.read`	Read customer information
`customer.update`	Update customer information
`customer-group.create`	Create customer group
`customer-group.read`	Read customer group
`customer-group.update`	Update customer group
`discount-code.create`	Create discount code
`discount-code.read`	Read discount code information
`discount-code.update`	Update discount code information
`inventory.create`	Create inventory
`inventory.read`	Read inventory information
`inventory.update`	Update inventory information
`order.create`	Create order (from cart, quote, import)
`order.read`	Read order information
`order.update`	Update order information
`product-discount.create`	Create product discount
`product-discount.read`	Read product discount
`product-discount.update`	Update product discount
`product-search.read`	Search products
`product-selection.create`	Create product selection
`product-selection.read`	Read product selection
`product-selection.update`	Update product selection
`product-type.create`	Create product type
`product-type.read`	Read product type
`product-type.update`	Update product type
`products.create`	Create product information
`products.read`	Read product information
`products.update`	Update product information
`project.read`	Read project information
`quote.create`	Create quote
`quote.read`	Read quote information
`quote.update`	Update quote information
`quote-request.create`	Create quote request
`quote-request.read`	Read quote request
`quote-request.update`	Update quote request
`staged-quote.create`	Create staged quote
`staged-quote.read`	Read staged quote
`staged-quote.update`	Update staged quote
`standalone-price.create`	Create standalone price
`standalone-price.read`	Read standalone price
`standalone-price.update`	Update standalone price
`store.create`	Create store
`store.read`	Read store
`store.update`	Update store

Agent Essentials

Agent Essentials allows agent frameworks to interact with Composable Commerce through function calling. It supports a subset of the commercetools API using the TypeScript SDK.

Agent Essentials requires Node 18 (or later). To get started, install @commercetools/agent-essentials:

npm install @commercetools/agent-essentials

Usage

Configure Agent Essentials with your API Client credentials. Your API Client must include scopes for each enabled action. For example, to enable products.read, the 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 { CommercetoolsAgentEssentials } from '@commercetools/agent-essentials/langchain';

const commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({
  authConfig: {
    type: 'client_credentials',
    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 integrates with LangChain and AI SDK by Vercel. Pass the tools to your agent executor:

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

const tools = commercetoolsAgentEssentials.getTools();

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

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

Set up an MCP server

You can also expose your own MCP server using CommercetoolsAgentEssentials:

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

const server = new CommercetoolsAgentEssentials({
  authConfig: {
    type: 'client_credentials',
    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 list of tools available to your agent.

const tools = commercetoolsAgentEssentials.getTools();

You can also use the Streamable HTTP server with the Agent Essentials like an SDK and develop on it.

import {
  CommercetoolsAgentEssentials,
  CommercetoolsAgentEssentialsStreamable,
} from '@commercetools/agent-essentials/modelcontextprotocol';
import express from 'express';

const expressApp = express();

const agentServer = new CommercetoolsAgentEssentials({
  authConfig: {
    type: 'client_credentials',
    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,
      },
    },
  },
});

const serverStreamable = new CommercetoolsAgentEssentialsStreamable({
  stateless: false, // make the MCP server stateless/stateful
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
  server: agentServer,
  app: expressApp, // optional express app instance
});

serverStreamable.listen(8888, function () {
  console.log('listening on 8888');
});

Without using the CommercetoolsAgentEssentials, you can directly use only the CommercetoolsAgentEssentialsStreamable class.

import { CommercetoolsAgentEssentialsStreamable } from '@commercetools/agent-essentials/modelcontextprotocol';
import express from 'express';

const expressApp = express();

const server = new CommercetoolsAgentEssentialsStreamable({
  authConfig: {
    type: 'client_credentials',
    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: {
      project: {
        read: true,
      },
      // other tools can go here
    },
  },

  stateless: false,
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
  app: expressApp,
});

server.listen(8888, function () {
  console.log('listening on 8888');
});

When developing locally, do not commit linked packages in package.json to your repository.

Essentials MCP

Placeholder values.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Authentication Types.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Setup STDIO Transport MCP Server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Installation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Using auth_token authentication.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Use with Claude Desktop.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Setup Streamable HTTP Transport MCP Server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Installation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Use with Claude Desktop.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Available tools.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Special Tool Options.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Individual Tools.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Agent Essentials.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Usage.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Tools.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set up an MCP server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

getTools().css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Placeholder values

Authentication Types

Setup STDIO Transport MCP Server

Installation

Using auth_token authentication

Use with Claude Desktop

Setup Streamable HTTP Transport MCP Server

Installation

Use with Claude Desktop

Available tools

Special Tool Options

Individual Tools

Agent Essentials

Usage

Tools

Set up an MCP server

getTools()