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.
Placeholder | Replace with | From |
---|---|---|
{PROJECT_KEY} | project_key | your API Client |
{CLIENT_ID} | client_id | your API Client |
{CLIENT_SECRET} | secret | your API Client |
{AUTH_URL} | your Authorization URL | Request an access token using the Composable Commerce OAuth 2.0 service |
{API_URL} | your API URL | Hosts |
Installation
Use the following commands to run Essentials MCP using npx:
npx -y @commercetools/mcp-essentials \
--tools=all \
--clientId=CLIENT_ID \
--clientSecret=CLIENT_SECRET \
--projectKey=PROJECT_KEY \
--authUrl=AUTH_URL \
--apiUrl=API_URL
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
Use with Claude Desktop
claude_desktop_config.json
. See the For Claude Desktop Users quickstart guide for more information.{
"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"
]
}
}
}
"--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 |
Individual Tools
Agent Essentials
Agent Essentials requires Node 18 (or later) and can be installed using the following command:
npm install @commercetools/agent-essentials
Usage
products: { read: true }
, your API client must have the view_products
scope.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()
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();
package.json
to your repository when doing local development.