[!IMPORTANT]

Commerce MCP is provided free of charge as an early access service. Our Service Level Agreement do not apply to Commerce MCP, and it is provided on an "as-is" basis.

commercetools MCP Essentials

This repository contains both a MCP server (which you can integrate with many MCP clients) and agent essentials 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/mcp-essentials --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/mcp-essentials --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/mcp-essentials --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/mcp-essentials --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/mcp-essentials --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/mcp-essentials --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.

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

To view information on how to locally run the bootstrapped MCP server, see this README.

[!IMPORTANT]

To load all the available tools set --tools=all and --isAdmin=true, all the available tools will be loaded into the MCP server. To limit the number of loaded tools set --tools=all.read for read-only tools or --tools=carts.read,quote.create,quote.read,... To disable dynamic tools loading set the dynamicToolLoadingThreshold to a very high value e.g --dynamicToolLoadingThreshold=650.

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

To view information on how to locally run the bootstrapped MCP server, see this README.

Refer to our official public documentation for a more advanced and comprehensive guide on how to get the most out of our MCP offerings.

{

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 = commercetoolsAgentEssentials.getTools();

#### Custom Tools

The self managed `@commercetools/agent-essentials` 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 MCP essentials or to give users complete control and customization of their tools behaviour and how it interact with the underlying LLM.

usage

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsAgentEssentials.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/mcp-essentials` MCP server now supports Streamable HTTP (remote) server.

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

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 Agent Essentials like an SDK and develop on it.

import express from "express";

import {

CommercetoolsAgentEssentials,

CommercetoolsAgentEssentialsStreamable,

} from "@commercetools/agent-essentials/modelcontextprotocol";

const expressApp = express();

const getAgentServer = async () => {

return CommercetoolsAgentEssentials.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 CommercetoolsAgentEssentialsStreamable({

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 `CommercetoolsAgentEssentials`, you can directly use only the `CommercetoolsAgentEssentialsStreamable` class and the agent server will be bootstrapped internally.

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,

app: expressApp,

streamableHttpOptions: {

sessionIdGenerator: undefined,

},

});

server.listen(8888, function () {

console.log("listening on 8888");

});

// Code block