Managed MCP Servers

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCEPRODUCT CATALOG

View, create, update, and delete Managed MCP Server configurations for your Project.

Managed MCP Servers expose a set of tools to AI agents through the Model Context Protocol (MCP). Each MCP Server configuration defines which tools are available and how AI agents connect to your commercetools Project.
Managed MCP Servers provide the hosted variant of Commerce MCP. For a conceptual overview and the available tools, see the Commerce MCP documentation. To run and extend the server yourself, see Self-hosted Commerce MCP.
To access Managed MCP Server configuration endpoints, use an API Client with the view_mcp_servers:{projectKey} or manage_mcp_servers:{projectKey} scopes. To learn how to use the Managed MCP Server itself, see Use the MCP Server with a client.
Each Managed MCP Server has a unique key within the Project. The server URL is generated automatically from your region, domain, Project key, and MCP Server key in the following format: https://mcp.{region}.{domain}/projects/{projectKey}/{mcpServerKey}. For example, consider a Project in the europe-west1.gcp region with the key my-project. If you create an MCP Server with the key my-mcp-server, the server URL is https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/my-mcp-server.
A maximum of 1 000 000 tool invocations can be made per Project per month. Learn more about this limit.

Representations

McpServer

Represents an MCP Server configuration that exposes a set of tools to AI agents via the Model Context Protocol.

id​
String​

Unique identifier of the MCP Server.

version​
Int​

Current version of the MCP Server.

key​
String​

User-defined unique identifier of the MCP Server within a Project.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
LocalizedString​

Name of the MCP Server.

description​
LocalizedString​

Description of the MCP Server.

state​
McpServerState​
State of the MCP Server. A Disabled MCP Server rejects all AI agent tool requests.
mcpServer​
McpServerConfig​

Configuration of the MCP Server connection.

createdAt​
DateTime​

Date and time (UTC) the MCP Server was initially created.

createdBy​
CreatedBy​

IDs and references that created the MCP Server.

lastModifiedAt​
DateTime​

Date and time (UTC) the MCP Server was last updated.

lastModifiedBy​
LastModifiedBy​

IDs and references that last modified the MCP Server.

McpServerConfig

Connection configuration of an MCP Server. The type discriminator determines the concrete configuration shape and the set of tools available for this MCP Server. Only CommerceMcpServerConfig is supported.
type​
String​
"CommerceMCP"

MCP Server type. Determines the shape of the configuration and the set of tools available for this MCP Server.

CommerceMcpServerConfig

Connection configuration of a Commerce MCP Server. Exposes the Commerce MCP Server tools to AI agents.
type​
String​
"CommerceMCP"

MCP Server type. Determines the shape of the configuration and the set of tools available for this MCP Server.

majorVersion​
String​
Major version of this MCP Server type. Supported versions are v1 (deprecated) and v4.
Can be "v1", or "v4"​
url​
String​
URL of the MCP Server. Generated by the system from the region, domain, Project key, and MCP Server key. Format: https://mcp.{region}.{domain}/projects/{projectKey}/{mcpServerKey}
tools​
Array of McpServerTool​
List of tools enabled for this MCP Server. Use all to enable all available tools, or specify individual tool names such as read_products or create_orders. To reduce the number of LLM turns and improve overall performance, it is advisable to expose only the tools that are necessary, or at least minimize the exposure of tools that are unlikely to be used.
toolCustomizations​
Array of ToolCustomization​
Per-tool customizations applied at tools/list and tools/call time, such as overriding a tool's description or constraining its parameters.
jsonOutputFiltering​
McpServerJsonOutputFiltering​

Response field-filtering rules applied to tool responses.

toolOutputFormatting​
McpServerToolOutputFormatting​

Output formatting applied to tool responses. When absent, responses are left untouched.

Example: json
{
  "type": "CommerceMCP",
  "majorVersion": "v4",
  "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
  "tools": [
    "read_cart_discounts",
    "read_product_discounts",
    "read_discount_codes"
  ],
  "toolCustomizations": [
    {
      "tool": "read_cart_discounts",
      "description": "Read cart discounts to audit active promotions and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores."
    },
    {
      "tool": "read_discount_codes",
      "description": "Read discount codes to check whether any active code is effectively unrestricted, for example no maximum number of applications and no validity window."
    }
  ],
  "jsonOutputFiltering": {
    "drop": {
      "fieldNames": [
        "createdBy",
        "lastModifiedBy"
      ]
    }
  },
  "toolOutputFormatting": "JsonToTabular"
}

McpServerTool

Identifies a tool that can be enabled on an MCP Server. For more information about the functions of each tool, see Commerce MCP Server tools.
all

Enables all available tools, including read, create, and update operations. For security and performance, enable this only when broad access is required.

read_all

Enables all read-only tools.

create_applications

Creates Applications.

read_applications

Reads Applications.

update_applications

Updates Applications.

create_attribute_groups

Creates Attribute Groups.

read_attribute_groups

Reads Attribute Groups.

update_attribute_groups

Updates Attribute Groups.

create_bulk

Creates resources in bulk.

update_bulk

Updates resources in bulk.

create_business_units

Creates Business Units.

read_business_units

Reads Business Units.

update_business_units

Updates Business Units.

create_cart_discounts

Creates Cart Discounts.

read_cart_discounts

Reads Cart Discounts.

update_cart_discounts

Updates Cart Discounts.

create_carts

Creates Carts.

read_carts

Reads Carts.

update_carts

Updates Carts.

replicate_carts

Replicates an existing Cart or Order into a new Cart.

create_categories

Creates Categories.

read_categories

Reads Categories.

update_categories

Updates Categories.

create_channels

Creates Channels.

read_channels

Reads Channels.

update_channels

Updates Channels.

create_custom_objects

Creates Custom Objects.

read_custom_objects

Reads Custom Objects.

update_custom_objects

Updates Custom Objects.

create_customer_groups

Creates Customer Groups.

read_customer_groups

Reads Customer Groups.

update_customer_groups

Updates Customer Groups.

read_customer_search

Searches for Customers.

create_customers

Creates Customers.

read_customers

Reads Customers.

update_customers

Updates Customers.

create_discount_codes

Creates Discount Codes.

read_discount_codes

Reads Discount Codes.

update_discount_codes

Updates Discount Codes.

create_extensions

Creates API Extensions.

read_extensions

Reads API Extensions.

update_extensions

Updates API Extensions.

create_inventory

Creates Inventory.

read_inventory

Reads Inventory.

update_inventory

Updates Inventory.

read_messages

Reads Messages.

create_orders

Creates Orders.

read_orders

Reads Orders.

update_orders

Updates Orders.

create_payment_integrations

Creates Payment Integrations.

read_payment_integrations

Reads Payment Integrations.

update_payment_integrations

Updates Payment Integrations.

update_payment_intents

Updates Payment Intents.

create_payment_methods

Creates Payment Methods.

read_payment_methods

Reads Payment Methods.

update_payment_methods

Updates Payment Methods.

create_payments

Creates Payments.

read_payments

Reads Payments.

update_payments

Updates Payments.

create_product_discounts

Creates Product Discounts.

read_product_discounts

Reads Product Discounts.

update_product_discounts

Updates Product Discounts.

read_product_projections

Reads Product Projections.

read_product_search

Searches for Products.

create_product_selections

Creates Product Selections.

read_product_selections

Reads Product Selections.

update_product_selections

Updates Product Selections.

create_product_tailoring

Creates Product Tailoring.

read_product_tailoring

Reads Product Tailoring.

update_product_tailoring

Updates Product Tailoring.

create_product_types

Creates Product Types.

read_product_types

Reads Product Types.

update_product_types

Updates Product Types.

create_products

Creates Products.

read_products

Reads Products.

update_products

Updates Products.

read_project

Reads Project settings.

update_project

Updates Project settings.

create_quote_requests

Creates Quote Requests.

read_quote_requests

Reads Quote Requests.

update_quote_requests

Updates Quote Requests.

create_quotes

Creates Quotes.

read_quotes

Reads Quotes.

update_quotes

Updates Quotes.

create_recurring_orders

Creates Recurring Orders.

read_recurring_orders

Reads Recurring Orders.

update_recurring_orders

Updates Recurring Orders.

create_reviews

Creates Reviews.

read_reviews

Reads Reviews.

update_reviews

Updates Reviews.

create_shipping_methods

Creates Shipping Methods.

read_shipping_methods

Reads Shipping Methods.

update_shipping_methods

Updates Shipping Methods.

create_shopping_lists

Creates Shopping Lists.

read_shopping_lists

Reads Shopping Lists.

update_shopping_lists

Updates Shopping Lists.

create_staged_quotes

Creates Staged Quotes.

read_staged_quotes

Reads Staged Quotes.

update_staged_quotes

Updates Staged Quotes.

create_standalone_prices

Creates Standalone Prices.

read_standalone_prices

Reads Standalone Prices.

update_standalone_prices

Updates Standalone Prices.

create_states

Creates States.

read_states

Reads States.

update_states

Updates States.

create_stores

Creates Stores.

read_stores

Reads Stores.

update_stores

Updates Stores.

create_subscriptions

Creates Subscriptions.

read_subscriptions

Reads Subscriptions.

update_subscriptions

Updates Subscriptions.

create_tax_categories

Creates Tax Categories.

read_tax_categories

Reads Tax Categories.

update_tax_categories

Updates Tax Categories.

create_transactions

Creates Transactions.

read_transactions

Reads Transactions.

create_types

Creates Types.

read_types

Reads Types.

update_types

Updates Types.

create_zones

Creates Zones.

read_zones

Reads Zones.

update_zones

Updates Zones.

McpServerType

Describes an MCP Server type and one of its major versions, including the catalog of tools available for it. Use this catalog to discover which tools you can enable on a McpServer of this type.
type​
String​
Identifier of the MCP Server type, such as CommerceMCP.
majorVersion​
String​
Major version of the MCP Server type, such as v4.
tools​
Array of McpServerTypeTool​

Tools available for this MCP Server type and major version.

Example: json
{
  "type": "CommerceMCP",
  "majorVersion": "v4",
  "tools": [
    {
      "name": "read_products",
      "description": "Search and retrieve product data from the catalog, including prices, variants, and attributes.",
      "operationType": "read",
      "groups": [
        "all",
        "read_all"
      ]
    },
    {
      "name": "create_orders",
      "description": "Create new orders from existing carts.",
      "operationType": "write",
      "groups": [
        "all"
      ]
    }
  ]
}

McpServerTypeTool

Describes a single tool available for an MCP Server type and major version.

name​
String​
Identifier of the tool, such as read_products or create_orders. Matches a value of McpServerTool.
description​
String​

Human-readable description of what the tool does. Omitted when no description is available.

operationType​
String​
Whether the tool reads (read) or modifies (write) data.
Can be "read", or "write"​
groups​
Array of String​
Group identifiers the tool belongs to, such as all or read_all. Empty when the tool belongs to no group.

McpServerDraft

Draft representation for creating a new MCP Server.

key​
String​

User-defined unique identifier for the MCP Server. Must be unique within the Project.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
LocalizedString​

Name of the MCP Server.

description​
LocalizedString​

Description of the MCP Server.

state​
McpServerState​

State of the MCP Server.

Default: Enabled​
mcpServer​
McpServerConfigDraft​

Configuration of the MCP Server connection.

McpServerConfigDraft

Connection configuration for creating or updating an MCP Server. The type discriminator determines the concrete configuration shape and the set of tools available for this MCP Server. Only CommerceMcpServerConfigDraft is supported.
type​
String​
"CommerceMCP"

MCP Server type. Determines the shape of the configuration and the set of tools available for this MCP Server.

CommerceMcpServerConfigDraft

Connection configuration for creating or updating a Commerce MCP Server.

type​
String​
"CommerceMCP"

MCP Server type. Determines the shape of the configuration and the set of tools available for this MCP Server.

majorVersion​
String​
Major version of this MCP Server type. Supported versions are v1 (deprecated) and v4.
Can be "v1", or "v4"​
tools​
Array of McpServerTool​
List of tools to enable for this MCP Server. Use all to enable all available tools, or specify individual tool names such as read_products or create_orders. To reduce the number of LLM turns and improve overall performance, it is advisable to expose only the tools that are necessary, or at least minimize the exposure of tools that are unlikely to be used.
toolCustomizations​
Array of ToolCustomization​
Per-tool customizations applied at tools/list and tools/call time, such as overriding a tool's description or constraining its parameters.
jsonOutputFiltering​
McpServerJsonOutputFiltering​

Response field-filtering rules applied to tool responses.

toolOutputFormatting​
McpServerToolOutputFormatting​

Output formatting applied to tool responses. When absent, responses are left untouched.

Example: json
{
  "type": "CommerceMCP",
  "majorVersion": "v4",
  "tools": [
    "read_product_search",
    "read_categories",
    "read_orders"
  ],
  "toolCustomizations": [
    {
      "tool": "read_product_search",
      "description": "Look for products in the catalog. Always filter by category when the customer mentions a department.",
      "parameters": [
        {
          "name": "staged",
          "const": false
        }
      ]
    }
  ],
  "jsonOutputFiltering": {
    "redact": {
      "fieldNameContains": [
        "phone",
        "password"
      ]
    },
    "drop": {
      "fieldNames": [
        "billingAddress",
        "shippingAddress",
        "paymentInfo"
      ]
    },
    "redactedWith": "[REDACTED]"
  }
}

McpServerPagedQueryResponse

PagedQueryResult with results containing an array of McpServer.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false.
results​
Array of McpServer​

MCP Servers matching the query.

McpServerState

State of the MCP Server. A Disabled MCP Server rejects all AI agent tool requests while keeping its configuration editable. Defaults to Enabled when not provided on creation.
Enabled

The MCP Server is active and accepts AI agent tool requests.

Disabled

The MCP Server rejects all AI agent tool requests while keeping its configuration editable.

McpServerToolOutputFormatting

Output formatting applied to every tools/call response on the MCP Server. The value names the conversion performed; when the field is absent, the response content shape is left untouched.
  • JsonToTabular: converts JSON tool output into a tabular representation.
JsonToTabular

Converts JSON tool output into a tabular representation to reduce token count.

ToolCustomization

Customization applied to a single tool at tools/list and tools/call time. At least one of description or a non-empty parameters list must be present; a customization with neither has no effect and is rejected. Parameter names within parameters must be unique.
tool​
McpServerTool​
Name of the tool to customize, such as read_products or create_orders. Must be one of the tools enabled on the MCP Server.
description​
String​

Replacement description for the tool, shown to the AI agent.

parameters​
Array of ParameterOverride​

Overrides applied to individual parameters of the tool's input schema.

ParameterOverride

Override applied to a single parameter of a tool's input schema. At least one of description, const, default, or allowedTypes must be present. const is mutually exclusive with both default and allowedTypes. Parameter values are JSON values.
name​
String​

Name of the parameter in the tool's input schema to override.

description​
String​

Replacement description for the parameter, shown to the AI agent.

const​
Any​
Pins the parameter to a fixed value. Mutually exclusive with default and allowedTypes.
default​
Any​
Default value applied when the caller omits the parameter. Mutually exclusive with const.
allowedTypes​
Array of Any​
Restricts accepted values to this set. Mutually exclusive with const.

McpServerJsonOutputFiltering

Response field-filtering rules applied to tools/call results on the MCP Server. Every field is optional; an empty object filters nothing.
redact​
McpServerJsonOutputFilteringMatcher​

Fields whose values are replaced with a placeholder. The field itself is kept.

drop​
McpServerJsonOutputFilteringMatcher​

Fields that are removed entirely from the response.

fieldPathsToKeep​
Array of String​
Exact dotted paths kept even when they would otherwise match redact or drop.
redactedWith​
String​
Placeholder written in place of redacted values. When unset, the MCP Server applies its own default ([REDACTED]).

McpServerJsonOutputFilteringMatcher

One match group for McpServerJsonOutputFiltering. Selects fields three ways, each with a fixed case-sensitivity rule. All fields are optional.
  • fieldPaths: exact dotted path, for example customer.password. Matched case-sensitively.
  • fieldNames: exact field name at any depth, for example password. Matched case-sensitively.
  • fieldNameContains: substring of a field name at any depth, for example secret catching clientSecret. Matched case-insensitively to widen the net.
fieldPaths​
Array of String​
Exact dotted paths to match, for example customer.password. Matched case-sensitively.
fieldNames​
Array of String​
Exact field names to match at any depth, for example password. Matched case-sensitively.
fieldNameContains​
Array of String​
Substrings to match against field names at any depth, for example secret. Matched case-insensitively.

McpServerUpdate

Update payload for an MCP Server. Specifies the expected version and the update actions to apply.

version​
Int​
Expected version of the MCP Server on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error is returned.
actions​
Array of McpServerUpdateAction​

Update actions to be performed on the MCP Server.

Get MCP Server

Get MCP Server by ID

GET
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id}
OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}view_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the McpServer.
Response:
200

McpServer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-01T10:30:00.000Z",
  "key": "promo-audit-server",
  "name": {
    "en-US": "Promo audit agent",
    "de-DE": "Aktions-Audit-Agent",
    "fr-FR": "Agent d'audit des promotions",
    "es-ES": "Agente de auditoría de promociones"
  },
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
    "tools": ["read_cart_discounts", "read_product_discounts", "read_discount_codes"],
    "toolCustomizations": [
      {
        "tool": "read_cart_discounts",
        "description": "Read cart discounts to audit the promotions configured in this Project and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores. Report findings only; this server cannot change discounts, and it has no access to orders or customers."
      }
    ]
  }
}

Get MCP Server by key

GET
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key}
OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}view_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the McpServer.
Response:
200

McpServer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-01T10:30:00.000Z",
  "key": "promo-audit-server",
  "name": {
    "en-US": "Promo audit agent",
    "de-DE": "Aktions-Audit-Agent",
    "fr-FR": "Agent d'audit des promotions",
    "es-ES": "Agente de auditoría de promociones"
  },
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
    "tools": ["read_cart_discounts", "read_product_discounts", "read_discount_codes"],
    "toolCustomizations": [
      {
        "tool": "read_cart_discounts",
        "description": "Read cart discounts to audit the promotions configured in this Project and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores. Report findings only; this server cannot change discounts, and it has no access to orders or customers."
      }
    ]
  }
}

Query MCP Servers

GET
https://api.{region}.commercetools.com/{projectKey}/mcp-servers
OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}view_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
sort
​
Sort
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
Response:
200

McpServerPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/mcp-servers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "version": 1,
      "createdAt": "2026-07-01T10:30:00.000Z",
      "lastModifiedAt": "2026-07-01T10:30:00.000Z",
      "key": "my-mcp-server",
      "state": "Enabled",
      "mcpServer": {
        "type": "CommerceMCP",
        "majorVersion": "v4",
        "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/my-mcp-server",
        "tools": ["read_products", "read_orders", "read_customers"],
        "toolCustomizations": []
      }
    }
  ]
}

Query MCP Server types

GET
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/types
Returns the catalog of available MCP Server types, each with its major versions and the tools you can enable for them.
OAuth 2.0 Scopes:
manage_project:{projectKey}manage_mcp_servers:{projectKey}view_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Response:
200

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/mcp-servers/types -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: arrayjson
[
  {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "tools": [
      {
        "name": "read_products",
        "description": "Read product data.",
        "operationType": "read",
        "groups": ["all", "read_all"]
      },
      {
        "name": "create_orders",
        "description": "Create orders.",
        "operationType": "write",
        "groups": ["all"]
      }
    ]
  }
]

Get MCP Server type

GET
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/types/{mcpServerType}
Returns a single MCP Server type. When majorVersion is omitted, the latest major version is returned.
OAuth 2.0 Scopes:
manage_project:{projectKey}manage_mcp_servers:{projectKey}view_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
mcpServerType
​
String
​
type of the McpServerType, such as CommerceMCP.
Query parameters:
majorVersion
​
String
​
Major version to return, such as v4. When omitted, the latest major version is returned.
Response:
200

McpServerType

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/mcp-servers/types/{mcpServerType} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerTypejson
{
  "type": "CommerceMCP",
  "majorVersion": "v4",
  "tools": [
    {
      "name": "read_products",
      "description": "Search and retrieve product data from the catalog, including prices, variants, and attributes.",
      "operationType": "read",
      "groups": ["all", "read_all"]
    },
    {
      "name": "create_orders",
      "description": "Create new orders from existing carts.",
      "operationType": "write",
      "groups": ["all"]
    }
  ]
}

Create MCP Server

POST
https://api.{region}.commercetools.com/{projectKey}/mcp-servers

Creates a new MCP Server for the Project.

Specific Error Codes:

OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:McpServerDraftasapplication/json
Response:
201

McpServer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/mcp-servers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "my-mcp-server",
  "mcpServer" : {
    "type" : "CommerceMCP",
    "majorVersion" : "v4",
    "tools" : [ "read_products", "read_orders", "read_customers" ]
  }
}
DATA
201 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-01T10:30:00.000Z",
  "key": "promo-audit-server",
  "name": {
    "en-US": "Promo audit agent",
    "de-DE": "Aktions-Audit-Agent",
    "fr-FR": "Agent d'audit des promotions",
    "es-ES": "Agente de auditoría de promociones"
  },
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
    "tools": ["read_cart_discounts", "read_product_discounts", "read_discount_codes"],
    "toolCustomizations": [
      {
        "tool": "read_cart_discounts",
        "description": "Read cart discounts to audit the promotions configured in this Project and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores. Report findings only; this server cannot change discounts, and it has no access to orders or customers."
      }
    ]
  }
}

Update MCP Server

Update MCP Server by ID

POST
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id}

Specific Error Codes:

OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the McpServer.
Request Body:McpServerUpdateasapplication/json
Response:
200

McpServer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "addTool",
    "tool" : "create_carts"
  } ]
}
DATA
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 2,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-10T11:00:00.000Z",
  "key": "my-mcp-server",
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/my-mcp-server",
    "tools": ["read_products", "read_orders", "read_customers", "create_carts"],
    "toolCustomizations": []
  }
}

Update MCP Server by key

POST
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key}

Specific Error Codes:

OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the McpServer.
Request Body:McpServerUpdateasapplication/json
Response:
200

McpServer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "addTool",
    "tool" : "create_carts"
  } ]
}
DATA
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 2,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-10T11:00:00.000Z",
  "key": "my-mcp-server",
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/my-mcp-server",
    "tools": ["read_products", "read_orders", "read_customers", "create_carts"],
    "toolCustomizations": []
  }
}

Update actions

Add Tool

Adds a single tool to the MCP Server's list of enabled tools. Has no effect if the tool is already present.

action​
String​
"addTool"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
tool​
McpServerTool​
Name of the tool to add, such as read_products or create_orders.
Example: json
{
  "action": "addTool",
  "tool": "create_carts"
}

Remove Tool

Removes a single tool from the MCP Server's list of enabled tools. Returns an InvalidOperation error if the tool is not in the current list.
action​
String​
"removeTool"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
tool​
McpServerTool​
Name of the tool to remove, such as read_products or create_orders.
Example: json
{
  "action": "removeTool",
  "tool": "create_carts"
}

Set Tools

Replaces the entire list of tools enabled for the MCP Server.

action​
String​
"setTools"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
tools​
Array of McpServerTool​
New list of tools to set. Replaces the existing tools list entirely. Use all to enable all available tools, or specify individual tool names such as read_products or create_orders.
Example: json
{
  "action": "setTools",
  "tools": [
    "read_products",
    "read_categories",
    "read_orders"
  ]
}

Set Tool Customizations

Replaces the entire list of tool customizations on the MCP Server.
action​
String​
"setToolCustomizations"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
toolCustomizations​
Array of ToolCustomization​

New list of tool customizations. Replaces the existing list entirely.

Example: json
{
  "action": "setToolCustomizations",
  "toolCustomizations": [
    {
      "tool": "read_product_search",
      "description": "Look for products in the catalog. Always filter by category when the customer mentions a department.",
      "parameters": [
        {
          "name": "staged",
          "const": false
        }
      ]
    },
    {
      "tool": "read_orders",
      "description": "Look up orders for customer support. Always ask for the order number before searching."
    }
  ]
}

Add Tool Customization

Adds a single tool customization to the MCP Server. Returns an InvalidOperation error if a customization for the same tool already exists.
action​
String​
"addToolCustomization"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
toolCustomization​
ToolCustomization​

Tool customization to add.

Example: json
{
  "action": "addToolCustomization",
  "toolCustomization": {
    "tool": "read_orders",
    "description": "Look up orders for customer support. Always ask for the order number before searching. Do not reveal payment details to the customer.",
    "parameters": [
      {
        "name": "limit",
        "default": 5
      }
    ]
  }
}

Remove Tool Customization

Removes the tool customization matching the given tool name. Has no effect if no customization exists for that tool.
action​
String​
"removeToolCustomization"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
toolCustomization​
RemoveToolCustomizationTarget​

Identifies the tool customization to remove by its tool name.

Example: json
{
  "action": "removeToolCustomization",
  "toolCustomization": {
    "tool": "read_orders"
  }
}

Remove Tool Customization Target

Identifies a tool customization to remove by its tool name.
tool​
McpServerTool​

Name of the tool whose customization is removed.

Set Name

Sets the localized name of the MCP Server.

action​
String​
"setName"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
name​
LocalizedString​

Value to set. If empty or absent, the existing name is removed.

Example: json
{
  "action": "setName",
  "name": {
    "en-US": "Storefront agent server",
    "de-DE": "Storefront-Agent-Server",
    "fr-FR": "Serveur d'agent de vitrine",
    "es-ES": "Servidor de agente de escaparate"
  }
}

Set Description

Sets the localized description of the MCP Server.

action​
String​
"setDescription"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
description​
LocalizedString​

Value to set. If empty or absent, the existing description is removed.

Example: json
{
  "action": "setDescription",
  "description": {
    "en-US": "Read-only catalog access for the storefront agent.",
    "de-DE": "Nur-Lese-Zugriff auf den Katalog für den Storefront-Agenten.",
    "fr-FR": "Accès en lecture seule au catalogue pour l'agent de vitrine.",
    "es-ES": "Acceso de solo lectura al catálogo para el agente de escaparate."
  }
}

Set State

Sets the state of the MCP Server. A Disabled MCP Server rejects all AI agent tool requests.
action​
String​
"setState"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
state​
McpServerState​

New state to set.

Example: json
{
  "action": "setState",
  "state": "Disabled"
}

Set JSON Output Filtering

Sets the response field-filtering rules applied to tool responses.
action​
String​
"setJsonOutputFiltering"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
jsonOutputFiltering​
McpServerJsonOutputFiltering​

Value to set. The existing configuration is entirely replaced with this value. If absent, the existing filtering configuration is removed.

Example: json
{
  "action": "setJsonOutputFiltering",
  "jsonOutputFiltering": {
    "redact": {
      "fieldNameContains": [
        "phone",
        "password"
      ]
    },
    "drop": {
      "fieldNames": [
        "billingAddress",
        "shippingAddress",
        "paymentInfo",
        "createdBy",
        "lastModifiedBy"
      ]
    },
    "fieldPathsToKeep": [
      "customer.email",
      "order.orderNumber"
    ],
    "redactedWith": "[REDACTED]"
  }
}

Set Tool Output Formatting

Sets the output formatting applied to tool responses.
action​
String​
"setToolOutputFormatting"
Identifies the update action to perform, such as addTool, removeTool, or setTools.
toolOutputFormatting​
McpServerToolOutputFormatting​

Value to set. If absent, the existing formatting is removed.

Example: json
{
  "action": "setToolOutputFormatting",
  "toolOutputFormatting": "JsonToTabular"
}

Delete MCP Server

Delete MCP Server by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id}
OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the McpServer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

Response:
200

McpServer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/mcp-servers/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-01T10:30:00.000Z",
  "key": "promo-audit-server",
  "name": {
    "en-US": "Promo audit agent",
    "de-DE": "Aktions-Audit-Agent",
    "fr-FR": "Agent d'audit des promotions",
    "es-ES": "Agente de auditoría de promociones"
  },
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
    "tools": ["read_cart_discounts", "read_product_discounts", "read_discount_codes"],
    "toolCustomizations": [
      {
        "tool": "read_cart_discounts",
        "description": "Read cart discounts to audit the promotions configured in this Project and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores. Report findings only; this server cannot change discounts, and it has no access to orders or customers."
      }
    ]
  }
}

Delete MCP Server by key

DELETE
https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key}
OAuth 2.0 Scopes:
manage_mcp_servers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the McpServer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

Response:
200

McpServer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/mcp-servers/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: McpServerjson
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1,
  "createdAt": "2026-07-01T10:30:00.000Z",
  "lastModifiedAt": "2026-07-01T10:30:00.000Z",
  "key": "promo-audit-server",
  "name": {
    "en-US": "Promo audit agent",
    "de-DE": "Aktions-Audit-Agent",
    "fr-FR": "Agent d'audit des promotions",
    "es-ES": "Agente de auditoría de promociones"
  },
  "state": "Enabled",
  "mcpServer": {
    "type": "CommerceMCP",
    "majorVersion": "v4",
    "url": "https://mcp.europe-west1.gcp.commercetools.com/projects/my-project/promo-audit-server",
    "tools": ["read_cart_discounts", "read_product_discounts", "read_discount_codes"],
    "toolCustomizations": [
      {
        "tool": "read_cart_discounts",
        "description": "Read cart discounts to audit the promotions configured in this Project and flag any that look too broad, for example a discount with no cart predicate or one that applies across all stores. Report findings only; this server cannot change discounts, and it has no access to orders or customers."
      }
    ]
  }
}