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 modes

The authenticationMode field of an MCP Server determines how a client authenticates before it can call any tool. Managed MCP Servers support two authentication modes:
Authentication modeCredentialTypical useTools exposed
ClientCredentialsAPI ClientMachine-to-machine scenarios, typically autonomous AI agentsEvery tool configured on the MCP Server
CommercetoolsIdentityAn Identity account, the same account used to sign in to the Merchant CenterHuman-in-the-loop scenarios, typically AI assistantsOnly the configured tools that the user's Merchant Center permissions allow
ClientCredentials is the default if you create an MCP Server without an authenticationMode. To change the mode of an existing MCP Server, use the Set Authentication Mode update action. Each mode has its own authorization server. An access token obtained for one mode is rejected by an MCP Server configured for the other mode.
You can also use ClientCredentials for human-in-the-loop scenarios. In this case, you are responsible for filtering the appropriate tools for your users.

Tool filtering by Merchant Center permissions

On an MCP Server that uses CommercetoolsIdentity, a tool is available only if the Merchant Center permissions of the user who logs in grant a similar level of access in the Merchant Center. Permissions are combined across all the Teams the user belongs to in the Project.
For example, the read_orders tool requires the view_orders scope, and the create_orders, update_orders, and delete_orders tools require the manage_orders scope. A user with the View all: Carts and Orders permission can therefore use read_orders. A user with the View and edit all: Orders permission can additionally use create_orders, update_orders, and delete_orders.

Filtering has the following consequences:

  • The tool list that the client receives contains only the tools that the user is permitted to use.
  • If the user's permissions permit none of the tools configured on the MCP Server, the request is rejected.
  • Some permissions grant no tools, such as the Audit Log and Checkout permissions.
  • Permission changes take effect without reconfiguring the MCP Server.

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.