Get started with Managed MCP Servers

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

Set up and use Managed MCP Servers with AI agents.

The following guide demonstrates how to set up and use Managed MCP Servers with AI agents. It is split into two sections:

Create the MCP Server

This section walks through creating an MCP Server configuration and retrieving its URL. To skip the manual steps, download the Postman and Bruno collection to create and update MCP Servers. The included README explains how to import and use the collection.

Create an API Client and get a bearer token

To create Managed MCP Servers, you must create an API Client with the manage_mcp_servers:{projectKey} scope. You can create the API Client in the Merchant Center or by using the API Clients API.
In the following example request body, replace {projectKey} with your Project key:
Request bodyjson
{
  "name": "mcp-server-test",
  "scope": "manage_mcp_servers:{projectKey}"
}
In the response, note the id, secret, and scope values. Use these values to get a bearer token using the Client credentials flow.

Create an MCP Server configuration

When you create a Managed MCP Server configuration, you define which tools the AI agent can use. This example creates an MCP Server that can read Category and Product information.

For security and performance, only enable the tools required for your use case, instead of using all.
Using the bearer token you just obtained, send the following request body to the Create MCP Server endpoint:
Request body for creating an MCP Serverjson
{
  "key": "my-mcp-server",
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "tools": ["read_categories", "read_products"]
  }
}
A new MCP Server is Disabled unless you set state to Enabled. A Disabled MCP Server rejects all tool requests. You can enable it later with the Set State update action.
This MCP Server uses API Client authentication, because the authenticationMode field defaults to ClientCredentials. To let each user sign in with their Identity account instead, set authenticationMode to CommercetoolsIdentity. For a comparison of both modes, see authentication modes.
Request body for creating an MCP Server with Identity account authenticationjson
{
  "key": "my-identity-mcp-server",
  "state": "Enabled",
  "authenticationMode": "CommercetoolsIdentity",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "tools": ["read_categories", "read_products"]
  }
}
The response includes the MCP Server URL in mcpServer.url. Note this URL, because you need it to connect your AI agent to the MCP Server.
You can also retrieve the MCP Server URL later using the Get MCP Server by ID or Get MCP Server by key endpoint.

Use the MCP Server with a client

After the MCP Server is set up, an MCP client must authenticate before it can call any tools. The way it authenticates depends on the authenticationMode of the MCP Server. Three paths are available:
The examples below show the static bearer token setup for Claude Code, Cursor, and n8n. For other MCP clients, refer to your client's documentation.

Create an API Client for the MCP Server

To create an API Client for the MCP Server, use the API Clients API with the scope mcp:{projectKey}:{mcpServerKey}.
You can control the validity of the token with accessTokenValiditySeconds. The maximum validity for MCP Servers is 30 days (2592000 seconds).
In the following example request body, replace {projectKey} with your Project key and {mcpServerKey} with your MCP Server key:
Request body for creating an API Client for the MCP Serverjson
{
  "name": "mcp-server-client",
  "scope": "mcp:{projectKey}:{mcpServerKey}",
  "accessTokenValiditySeconds": 604800
}

In this example, the token validity is set to seven days (604800 seconds).

In the response, note the id, secret, and scope values.

Authenticate with a static bearer token

Use the API Client's id, secret, and scope to get a bearer token using the Client credentials flow.
The bearer token expires based on the accessTokenValiditySeconds value set when creating the API Client (maximum 30 days, or 2592000 seconds). To maintain connectivity after it expires, generate a new token using the same API Client credentials.

The scope allows only machine-to-machine interaction; it doesn't allow access to the Merchant Center or a specific Store.

Connect to Claude Code

Create or update .mcp.json in the root of your repository with the following content:
Server configuration for Claude Codejson
{
  "mcpServers": {
    "managed-mcp-servers": {
      "type": "http",
      "url": "<your-mcp-server-url>",
      "headers": {
        "Authorization": "Bearer <your-ctp-token>"
      }
    }
  }
}

Restart Claude Code and your MCP Server will be available.

Connect to Cursor

Open Settings > MCP and add a new server with the following details:
Server configuration for Cursorjson
{
  "mcpServers": {
    "managed-mcp-servers": {
      "type": "http",
      "url": "<your-mcp-server-url>",
      "headers": {
        "Authorization": "Bearer <your-ctp-token>"
      }
    }
  }
}

Restart Cursor and your MCP Server will be available.

Connect to n8n

  1. In n8n, create a Bearer Auth credential with your API Client token.
  2. Download the n8n-example-categories.json example workflow file.
  3. Create a new workflow, then in the top right select ... > Import from file to import the workflow file.
  4. In the Fetch Categories node, assign the credential and replace the endpoint URL with your MCP Server URL.
To test the workflow, open the webhook URL in your browser: https://<your-n8n-instance>/webhook/commerce-summary. You should see a list of categories from your Project.

Authenticate with OAuth 2.0 discovery

If your client supports the OAuth Client Credentials Extension, it handles the token exchange for you. You do not fetch or paste a token manually.

Configure your client with the MCP Server URL and the API Client credentials:

  • The API Client id is the OAuth client_id.
  • The API Client secret is the OAuth client_secret.
Your client discovers the authorization server and requests tokens automatically. For implementation examples, see the official MCP TypeScript and Python SDKs.

Authenticate with an Identity account

On an MCP Server that uses the CommercetoolsIdentity authentication mode, each user signs in with their own Identity account, the same account they use for the Merchant Center. You don't need an API Client, and there are no credentials to create or paste.

Configure your client with the MCP Server URL. The client discovers the authorization server from the MCP Server and opens a browser window, where the user signs in.

Your client must support OAuth 2.0 authorization code discovery. A client that only supports a static bearer token or the client credentials flow can't connect to an MCP Server in this mode.

The tools available to the client are the tools that the permissions of the user who logs in allow. For details, see tool filtering by Merchant Center permissions.