License and Scope of Use for Commerce MCP

Commerce MCP is provided under a dual-tier usage model based on the highly permissive MIT License with specific limitations on commercial use.

Permitted Use

Access to and use of Commerce MCP is governed by the following terms:

Non-Commercial Use (No Charge): The use of Commerce MCP is permitted for development, evaluation, and testing purposes at no charge. This non-commercial use is subject to a hard cap of 1,000,000 (one million) total tool invocations.
Commercial/Production Use (Required License): Any use of Commerce MCP in a production environment or for any other commercial purpose requires a paid license or subscription.

License Enforcement

While the underlying code adheres to the principles of the MIT License, the terms above constitute the binding agreement for utilizing Commerce MCP. commercetools reserves the right to review how customers are using Commerce MCP and to restrict or terminate access for unlicensed production use or for any non-commercial use that exceeds the stated 1,000,000 invocation limit.

commercetools Commerce MCP

This repository contains both an MCP server (which you can integrate with many MCP clients) and commerce agent that can be used from within agent frameworks.

commercetools Model Context Protocol

Setup

To run the commercetools MCP server using npx, use the following command:

Client Credentials Authentication (Default)

# To set up all available tools (authType is optional, defaults to client_credentials)
npx -y @commercetools/commerce-mcp --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# Explicitly specify client_credentials (optional)
npx -y @commercetools/commerce-mcp --tools=all --authType=client_credentials --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools
npx -y @commercetools/commerce-mcp --tools=all.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up specific tools
npx -y @commercetools/commerce-mcp --tools=products.read,products.create --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Access Token Authentication

# To set up all available tools with access token
npx -y @commercetools/commerce-mcp --tools=all --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools with access token
npx -y @commercetools/commerce-mcp --tools=all.read --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Make sure to replace CLIENT_ID, CLIENT_SECRET, PROJECT_KEY, AUTH_URL, API_URL, and ACCESS_TOKEN with your actual values. If using the customerId parameter, replace CUSTOMER_ID with the actual customer ID. Alternatively, you could set the API_KEY in your environment variables.

Authentication Options

The MCP server supports two authentication methods:

Authentication Type	Required Arguments	Description
`client_credentials` (default)	`--clientId`, `--clientSecret`	Uses API client credentials for authentication. `--authType=client_credentials` is optional since this is the default
`auth_token`	`--accessToken`, (optional `--clientId`, `--clientSecret`)	Uses a pre-existing access token for authentication. Requires `--authType=auth_token` and optional `--clientId` and `--clientSecret`

Usage with Claude Desktop

Add the following to your claude_desktop_config.json. See here for more details.

Client Credentials Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=30"
      ]
    }
  }
}

Note: You can optionally add "--authType=client_credentials" to be explicit, but it's not required since this is the default.

Access Token Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--authType=auth_token",
        "--accessToken=ACCESS_TOKEN",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL"
      ]
    }
  }
}

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

Available tools

Special Tool Options

Tool	Description
`all`	Enable all available tools (read, create, and update operations)
`all.read`	Enable all read-only tools (safe for read-only access)

Individual Tools

Tool	Description
`products.read`	Read product information
`products.create`	Create product information
`products.update`	Update product information
`project.read`	Read project information
`product-search.read`	Search products
`category.read`	Read category information
`category.create`	Create category
`category.update`	Update category
`channel.read`	Read channel information
`channel.create`	Create channel
`channel.update`	Update channel information
`product-selection.read`	Read product selection
`product-selection.create`	Create product selection
`product-selection.update`	Update product selection
`order.read`	Read order information
`order.create`	Create order (from cart, quote, import)
`order.update`	Update order information
`cart.read`	Read cart information
`cart.create`	Create cart
`cart.update`	Update cart information
`customer.read`	Read customer information
`customer.create`	Create customer
`customer.update`	Update customer information
`customer-group.read`	Read customer group
`customer-group.create`	Create customer group
`customer-group.update`	Update customer group
`quote.read`	Read quote information
`quote.create`	Create quote
`quote.update`	Update quote information
`quote-request.read`	Read quote request
`quote-request.create`	Create quote request
`quote-request.update`	Update quote request
`staged-quote.read`	Read staged quote
`staged-quote.create`	Create staged quote
`staged-quote.update`	Update staged quote
`standalone-price.read`	Read standalone price
`standalone-price.create`	Create standalone price
`standalone-price.update`	Update standalone price
`product-discount.read`	Read product discount
`product-discount.create`	Create product discount
`product-discount.update`	Update product discount
`cart-discount.read`	Read cart discount
`cart-discount.create`	Create cart discount
`cart-discount.update`	Update cart discount
`discount-code.read`	Read discount code information
`discount-code.create`	Create discount code
`discount-code.update`	Update discount code information
`product-type.read`	Read product type
`product-type.create`	Create product type
`product-type.update`	Update product type
`bulk.create`	Create entities in bulk
`bulk.update`	Update entities in bulk
`inventory.read`	Read inventory information
`inventory.create`	Create inventory
`inventory.update`	Update inventory information
`store.read`	Read store
`store.create`	Create store
`store.update`	Update store
`business-unit.read`	Read business unit
`business-unit.create`	Create business unit
`business-unit.update`	Update business unit
`payments.read`	Read payment information
`payments.create`	Create payment
`payments.update`	Update payment information
`tax-category.read`	Read tax category information
`tax-category.create`	Create tax category
`tax-category.update`	Update tax category information
`shipping-methods.read`	Read shipping method information
`shipping-methods.create`	Create shipping method
`shipping-methods.update`	Update shipping method information
`zone.read`	Read zone information
`zone.create`	Create zone
`zone.update`	Update zone information
`recurring-orders.read`	Read recurring order information
`recurring-orders.create`	Create recurring order
`recurring-orders.update`	Update recurring order information
`shopping-lists.read`	Read shopping list information
`shopping-lists.create`	Create shopping list
`shopping-lists.update`	Update shopping list information
`extensions.read`	Read extension information
`extensions.create`	Create extension
`extensions.update`	Update extension information
`subscriptions.read`	Read subscription information
`subscriptions.create`	Create subscription
`subscriptions.update`	Update subscription information
`payment-methods.read`	Read payment method information
`payment-methods.create`	Create payment method
`payment-methods.update`	Update payment method information
`product-tailoring.read`	Read product tailoring information
`product-tailoring.create`	Create product tailoring
`product-tailoring.update`	Update product tailoring information
`custom-objects.read`	Read custom object information
`custom-objects.create`	Create custom object
`custom-objects.update`	Update custom object information
`types.read`	Read type information
`types.create`	Create type
`types.update`	Update type information

To view information on how to develop the MCP server, see this README.

Dynamic Tool Loading

The MCP server includes a dynamic tool loading feature that automatically switches to a more efficient loading strategy when the number of enabled tools exceeds a configurable threshold. This helps optimize performance and reduce context usage when working with large numbers of tools.

How it works

Default threshold: 30 tools
Behavior: When the number of enabled tools exceeds the threshold, the server switches to dynamic tool loading

Configuration

You can configure the dynamic tool loading threshold in two ways:

Command Line Argument

npx -y @commercetools/commerce-mcp --tools=all --dynamicToolLoadingThreshold=50 --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Environment Variable

export DYNAMIC_TOOL_LOADING_THRESHOLD=50
npx -y @commercetools/commerce-mcp --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Example with Claude Desktop

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=25"
      ]
    }
  }
}

Commerce MCP

The commercetools Commerce MCP enables popular agent frameworks including LangChain, Vercel's AI SDK, and Model Context Protocol (MCP) to integrate with APIs through function calling. The library is not exhaustive of the entire commercetools API. It includes support for TypeScript and is built directly on top of the [Node][node-sdk] SDK.

Included below are basic instructions, but refer to the TypeScript package for more information.

TypeScript

Installation

You don't need this source code unless you want to modify the package. If you just want to use the package run:

npm install @commercetools/commerce-agent

Requirements

Node 18+

Usage

The library needs to be configured with your commercetools project credentials which are available in your Merchant center. Important: Ensure that the API client credentials have the necessary scopes aligned with the actions you configure in the commerce agent. For example, if you configure products: { read: true }, your API client must have the view_products scope. Additionally, configuration enables you to specify the types of actions that can be taken using the commerce agent.

Client Credentials Authentication (Default)

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/langchain";

const commercetoolsCommerceAgent = await CommercetoolsCommerceAgent.create({
  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,
      },
    },
  },
});

Access Token Authentication

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/langchain";

const commercetoolsCommerceAgent = await CommercetoolsCommerceAgent.create({
  authConfig: {
    type: "auth_token",
    accessToken: process.env.ACCESS_TOKEN!,
    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 commerce agent works with LangChain and Vercel's AI SDK and can be passed as a list of tools. For example:

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

const tools = commercetoolsCommerceAgent.getTools();

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

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

Model Context Protocol

The commercetools Commerce MCP also supports setting up your own MCP server. For example:

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsCommerceAgent.create({
  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()

Returns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:

const tools = commercetoolsCommerceAgent.getTools();

Custom Tools

The self managed @commercetools/commerce-agent includes supports for custom tools. A list of custom tools implementations can be passed over and registered at runtime by the bootstrapping MCP server. This is especially useful when the intended tool is not yet implemented into the Commerce MCP or to give users complete control and customization of their tools behaviour and how it interact with the underlying LLM.

usage

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsCommerceAgent.create({
  authConfig: {...},
  configuration: {
    customTools: [
      {
        name: "Get Project",
        method: "get_project",
        description: `This tool will fetch information about a commercetools project.\n\n
           This tool will accept a project and fetch information about the provided key. \n\n
          `, // It is important that this description is well details and explicitly descripts what this tool does and the paramenters it receieves/
        parameters: z.object({
          projectKey: z
            .string()
            .optional()
            .describe(
              "The key of the project to read. If not provided, the current project will be used."
            ),
        }),
        actions: {},
        execute: async (args: { projectKey: string }, api: ApiRoot) => {
          // already existing functions can be used here e.g const response = await import('ctService').getProject('demo-project-key-a7fc1182');
          const response = await api.withProjectKey(args).get().execute();
          return JSON.stringify(response);
        },
      },
      ...
    ],
    actions: {...},
  },
});
...

Streamable HTTP MCP server

As of version v2.0.0 of the @commercetools/commerce-mcp MCP server now supports Streamable HTTP (remote) server.

npx -y @commercetools/commerce-mcp \
  --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

You can connect to the running remote server using Claude by specifying the below in the claude_desktop_config.json file.

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

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

import express from "express";
import {
  CommercetoolsCommerceAgent,
  CommercetoolsCommerceAgentStreamable,
} from "@commercetools/commerce-agent/modelcontextprotocol";

const expressApp = express();

const getAgentServer = async () => {
  return CommercetoolsCommerceAgent.create({
    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 CommercetoolsCommerceAgentStreamable({
  stateless: false, // make the MCP server stateless/stateful
  server: getAgentServer,
  app: expressApp, // optional express app instance
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

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

Without using the CommercetoolsCommerceAgent, you can directly use only the CommercetoolsCommerceAgentStreamable class and the agent server will be bootstrapped internally.

import { CommercetoolsCommerceAgentStreamable } from "@commercetools/commerce-agent/modelcontextprotocol";
import express from "express";

const expressApp = express();

const server = new CommercetoolsCommerceAgentStreamable({
  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,
  app: expressApp,
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

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

License and Scope of Use for Commerce MCP

Commerce MCP is provided under a dual-tier usage model based on the highly permissive MIT License with specific limitations on commercial use.

Permitted Use

Access to and use of Commerce MCP is governed by the following terms:

Non-Commercial Use (No Charge): The use of Commerce MCP is permitted for development, evaluation, and testing purposes at no charge. This non-commercial use is subject to a hard cap of 1,000,000 (one million) total tool invocations.
Commercial/Production Use (Required License): Any use of Commerce MCP in a production environment or for any other commercial purpose requires a paid license or subscription.

License Enforcement

commercetools Commerce MCP

This repository contains both an MCP server (which you can integrate with many MCP clients) and commerce agent that can be used from within agent frameworks.

commercetools Model Context Protocol

Setup

To run the commercetools MCP server using npx, use the following command:

Client Credentials Authentication (Default)

# To set up all available tools (authType is optional, defaults to client_credentials)
npx -y @commercetools/commerce-mcp --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# Explicitly specify client_credentials (optional)
npx -y @commercetools/commerce-mcp --tools=all --authType=client_credentials --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools
npx -y @commercetools/commerce-mcp --tools=all.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up specific tools
npx -y @commercetools/commerce-mcp --tools=products.read,products.create --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Access Token Authentication

# To set up all available tools with access token
npx -y @commercetools/commerce-mcp --tools=all --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools with access token
npx -y @commercetools/commerce-mcp --tools=all.read --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Authentication Options

The MCP server supports two authentication methods:

Authentication Type	Required Arguments	Description
`client_credentials` (default)	`--clientId`, `--clientSecret`	Uses API client credentials for authentication. `--authType=client_credentials` is optional since this is the default
`auth_token`	`--accessToken`, (optional `--clientId`, `--clientSecret`)	Uses a pre-existing access token for authentication. Requires `--authType=auth_token` and optional `--clientId` and `--clientSecret`

Usage with Claude Desktop

Add the following to your claude_desktop_config.json. See here for more details.

Client Credentials Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=30"
      ]
    }
  }
}

Note: You can optionally add "--authType=client_credentials" to be explicit, but it's not required since this is the default.

Access Token Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--authType=auth_token",
        "--accessToken=ACCESS_TOKEN",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL"
      ]
    }
  }
}

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

Available tools

Special Tool Options

Tool	Description
`all`	Enable all available tools (read, create, and update operations)
`all.read`	Enable all read-only tools (safe for read-only access)

Individual Tools

Tool	Description
`products.read`	Read product information
`products.create`	Create product information
`products.update`	Update product information
`project.read`	Read project information
`product-search.read`	Search products
`category.read`	Read category information
`category.create`	Create category
`category.update`	Update category
`channel.read`	Read channel information
`channel.create`	Create channel
`channel.update`	Update channel information
`product-selection.read`	Read product selection
`product-selection.create`	Create product selection
`product-selection.update`	Update product selection
`order.read`	Read order information
`order.create`	Create order (from cart, quote, import)
`order.update`	Update order information
`cart.read`	Read cart information
`cart.create`	Create cart
`cart.update`	Update cart information
`customer.read`	Read customer information
`customer.create`	Create customer
`customer.update`	Update customer information
`customer-group.read`	Read customer group
`customer-group.create`	Create customer group
`customer-group.update`	Update customer group
`quote.read`	Read quote information
`quote.create`	Create quote
`quote.update`	Update quote information
`quote-request.read`	Read quote request
`quote-request.create`	Create quote request
`quote-request.update`	Update quote request
`staged-quote.read`	Read staged quote
`staged-quote.create`	Create staged quote
`staged-quote.update`	Update staged quote
`standalone-price.read`	Read standalone price
`standalone-price.create`	Create standalone price
`standalone-price.update`	Update standalone price
`product-discount.read`	Read product discount
`product-discount.create`	Create product discount
`product-discount.update`	Update product discount
`cart-discount.read`	Read cart discount
`cart-discount.create`	Create cart discount
`cart-discount.update`	Update cart discount
`discount-code.read`	Read discount code information
`discount-code.create`	Create discount code
`discount-code.update`	Update discount code information
`product-type.read`	Read product type
`product-type.create`	Create product type
`product-type.update`	Update product type
`bulk.create`	Create entities in bulk
`bulk.update`	Update entities in bulk
`inventory.read`	Read inventory information
`inventory.create`	Create inventory
`inventory.update`	Update inventory information
`store.read`	Read store
`store.create`	Create store
`store.update`	Update store
`business-unit.read`	Read business unit
`business-unit.create`	Create business unit
`business-unit.update`	Update business unit
`payments.read`	Read payment information
`payments.create`	Create payment
`payments.update`	Update payment information
`tax-category.read`	Read tax category information
`tax-category.create`	Create tax category
`tax-category.update`	Update tax category information
`shipping-methods.read`	Read shipping method information
`shipping-methods.create`	Create shipping method
`shipping-methods.update`	Update shipping method information
`zone.read`	Read zone information
`zone.create`	Create zone
`zone.update`	Update zone information
`recurring-orders.read`	Read recurring order information
`recurring-orders.create`	Create recurring order
`recurring-orders.update`	Update recurring order information
`shopping-lists.read`	Read shopping list information
`shopping-lists.create`	Create shopping list
`shopping-lists.update`	Update shopping list information
`extensions.read`	Read extension information
`extensions.create`	Create extension
`extensions.update`	Update extension information
`subscriptions.read`	Read subscription information
`subscriptions.create`	Create subscription
`subscriptions.update`	Update subscription information
`payment-methods.read`	Read payment method information
`payment-methods.create`	Create payment method
`payment-methods.update`	Update payment method information
`product-tailoring.read`	Read product tailoring information
`product-tailoring.create`	Create product tailoring
`product-tailoring.update`	Update product tailoring information
`custom-objects.read`	Read custom object information
`custom-objects.create`	Create custom object
`custom-objects.update`	Update custom object information
`types.read`	Read type information
`types.create`	Create type
`types.update`	Update type information

To view information on how to develop the MCP server, see this README.

Dynamic Tool Loading

How it works

Default threshold: 30 tools
Behavior: When the number of enabled tools exceeds the threshold, the server switches to dynamic tool loading

Configuration

You can configure the dynamic tool loading threshold in two ways:

Command Line Argument

npx -y @commercetools/commerce-mcp --tools=all --dynamicToolLoadingThreshold=50 --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Environment Variable

export DYNAMIC_TOOL_LOADING_THRESHOLD=50
npx -y @commercetools/commerce-mcp --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Example with Claude Desktop

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/commerce-mcp@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=25"
      ]
    }
  }
}

Commerce MCP

Included below are basic instructions, but refer to the TypeScript package for more information.

TypeScript

Installation

You don't need this source code unless you want to modify the package. If you just want to use the package run:

npm install @commercetools/commerce-agent

Requirements

Node 18+

Usage

Client Credentials Authentication (Default)

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/langchain";

const commercetoolsCommerceAgent = await CommercetoolsCommerceAgent.create({
  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,
      },
    },
  },
});

Access Token Authentication

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/langchain";

const commercetoolsCommerceAgent = await CommercetoolsCommerceAgent.create({
  authConfig: {
    type: "auth_token",
    accessToken: process.env.ACCESS_TOKEN!,
    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 commerce agent works with LangChain and Vercel's AI SDK and can be passed as a list of tools. For example:

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

const tools = commercetoolsCommerceAgent.getTools();

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

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

Model Context Protocol

The commercetools Commerce MCP also supports setting up your own MCP server. For example:

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsCommerceAgent.create({
  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()

Returns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:

const tools = commercetoolsCommerceAgent.getTools();

Custom Tools

usage

import { CommercetoolsCommerceAgent } from "@commercetools/commerce-agent/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsCommerceAgent.create({
  authConfig: {...},
  configuration: {
    customTools: [
      {
        name: "Get Project",
        method: "get_project",
        description: `This tool will fetch information about a commercetools project.\n\n
           This tool will accept a project and fetch information about the provided key. \n\n
          `, // It is important that this description is well details and explicitly descripts what this tool does and the paramenters it receieves/
        parameters: z.object({
          projectKey: z
            .string()
            .optional()
            .describe(
              "The key of the project to read. If not provided, the current project will be used."
            ),
        }),
        actions: {},
        execute: async (args: { projectKey: string }, api: ApiRoot) => {
          // already existing functions can be used here e.g const response = await import('ctService').getProject('demo-project-key-a7fc1182');
          const response = await api.withProjectKey(args).get().execute();
          return JSON.stringify(response);
        },
      },
      ...
    ],
    actions: {...},
  },
});
...

Streamable HTTP MCP server

As of version v2.0.0 of the @commercetools/commerce-mcp MCP server now supports Streamable HTTP (remote) server.

npx -y @commercetools/commerce-mcp \
  --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

You can connect to the running remote server using Claude by specifying the below in the claude_desktop_config.json file.

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

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

import express from "express";
import {
  CommercetoolsCommerceAgent,
  CommercetoolsCommerceAgentStreamable,
} from "@commercetools/commerce-agent/modelcontextprotocol";

const expressApp = express();

const getAgentServer = async () => {
  return CommercetoolsCommerceAgent.create({
    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 CommercetoolsCommerceAgentStreamable({
  stateless: false, // make the MCP server stateless/stateful
  server: getAgentServer,
  app: expressApp, // optional express app instance
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

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

Without using the CommercetoolsCommerceAgent, you can directly use only the CommercetoolsCommerceAgentStreamable class and the agent server will be bootstrapped internally.

import { CommercetoolsCommerceAgentStreamable } from "@commercetools/commerce-agent/modelcontextprotocol";
import express from "express";

const expressApp = express();

const server = new CommercetoolsCommerceAgentStreamable({
  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,
  app: expressApp,
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

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