Enable AI agents and assistants to integrate seamlessly with Composable Commerce through standardized function calling.
This toolkit provides a bridge between popular AI frameworks including Claude Desktop, LangChain, and AI SDK by Vercel, allowing them to interact with Composable Commerce APIs directly.
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.
| 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
Add the following configuration to your
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",
"--isAdmin=true",
"--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".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
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.