Managed MCP Servers overview

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCEPRODUCT CATALOG
Ask about this Page
Copy for LLM
View as Markdown

Managed MCP Servers let you securely connect AI assistants and AI agents to your Project through centralized MCP Server configurations.

Managed MCP Servers

Managed MCP Servers provide a managed entry point for AI assistants and fully autonomous AI agents to interact with your commercetools Project. AI assistants include human-in-the-loop tools such as ChatGPT or Claude, as well as development tools like Cursor or Claude Code. Managed MCP Servers expose tools (actions such as reading Products or creating Orders) through the Model Context Protocol (MCP).
Managed MCP Servers offer a hosted version of Commerce MCP with the same tools. Compared to a self-hosted Commerce MCP, Managed MCP Servers provide centralized configuration with guaranteed enforcement.
With a self-hosted deployment, the AI assistant or its user can change the local configuration. They can also use the API Client directly against the API, bypassing defined restrictions (see Confused Deputy Problem). With Managed MCP Servers, the AI assistant can only access the MCP Server. It cannot call the API directly.

Centralized configuration lets you easily roll out changes, such as adding or removing tools, to AI assistants. Because the configuration is available through the API, you can deploy changes through a pipeline alongside your AI agents. For example, you can test on a staging Project before promoting to production.

Platform Insights tracks the usage of MCP Servers, providing observability into how your AI assistants and AI agents use them.
You can also configure multiple MCP Servers, typically one per AI agent. Each AI agent gets a tailored set of tools, and its usage can be tracked individually in Platform Insights.
Managed MCP Servers include a UI for creating MCP Servers and changing their configuration from the Merchant Center. For more information, see Managed MCP Servers in the Merchant Center documentation.

When to self-host Commerce MCP

The Commerce MCP repository is open source, which makes it suitable for a few unique use cases:

  • Building completely custom tools that go beyond customizing existing ones.
  • Including the tool code directly in your AI agent framework (such as LangChain, Vercel AI, or Mastra) without a dedicated MCP Server. The tools are deployed alongside your AI agent.

Authentication use cases

Managed MCP Servers support two authentication modes:

  • Identity Account (Early Access): for human-in-the-loop scenarios, typically AI assistants. Use CommercetoolsIdentity to authenticate with an Identity Account that is also used in the Merchant Center. Tools are filtered according to the user's permissions. This mode is in early access. To get onboarded, contact your Customer Success Manager.
  • API Client: for machine-to-machine scenarios, typically autonomous AI agents. Authenticate with an API Client.

You can also use an API Client for human-in-the-loop scenarios. In this case, you are responsible for filtering the appropriate tools for your users.

Customize MCP Servers

You customize an MCP Server's configuration for two purposes:

  • Security: avoid exposing capabilities or data to prevent misuse or data leaks.
  • AI accuracy: unnecessary tools or data can confuse the AI and increase token usage.

Customize for security

To control what data the agent can access and whether it can make changes, you can:

  • remove access to specific tools.
  • filter fields and redact data.
  • fix some parameters to a constant value.

Customize for AI accuracy

The goal is to help the AI agent or AI assistant invoke the right tool on the first try. Reducing the number of tools and the amount of data returned also reduces token usage. To improve accuracy, you can:

  • Remove tools your AI agent doesn't need. For example, if your AI agent creates Product Discounts, remove tools for Cart Discounts and Discount Codes.
  • Filter fields from responses that your AI agent doesn't need. For example, if an AI agent analyzes how Products are purchased, the read_orders tool can return the lineItems field and filter out customer email, addresses, or shipping details.
  • Overwrite tool descriptions. The default description provides generic usage information, but you can add Project-specific guidance. For example, a search tool could include commonly used Categories or filters, and a Product creation tool could suggest which Tax Category to pick.

Your AI agent won't have the original tool description available. Base your new tool description on the existing one, so that your AI agent has all the information it needs to use the tool correctly.

Consider using an evaluation (Eval) framework while developing your AI agent. Eval frameworks let you run automated tests that verify your configuration changes improve accuracy. Public examples include Langfuse, Braintrust, and Promptfoo.

Versioning

Managed MCP Servers follow Semantic Versioning. When you create an MCP Server, you must provide the major version in the mcpServer.majorVersion field (for example, v4). New major versions are not applied automatically, giving you time to test. To switch to a new major version, either create a new MCP Server with the new version, or update the version. Old major versions remain supported until they are removed. At that point, an automatic update is applied.
The minor and patch versions are applied automatically. If you have enabled all or read_all for your MCP Server, new tools can become available through an automatic release. If you select tools individually, new tools are not added unless you explicitly include them in your configuration.

Compare versions between the managed and self-hosted Commerce MCP

The major versions aren't always directly aligned, because the self-hosted Commerce MCP needs additional major releases.

The tools in the managed Commerce MCP v4 are compatible with the self-hosted Commerce MCP 4.0.0 and upwards.

Next steps

To create and manage MCP Server configurations for your Project, see the MCP Servers API reference.