Developer MCP

Access commercetools documentation and schema content through the Developer MCP APIs (MCP server and Content API)

Developer IDEs or AI agents can connect to a public MCP server that provides tools to help build commerce solutions using commercetools products.

Developers building their own MCP servers or AI applications that work with commercetools documentation content and API references can access plain text (Markdown), natural language descriptions, and API schema forms of the content through an open REST API.

Developer MCP is a stateless offering that does not require authentication and serves publicly available content.

MCP Server

The server is accessible via streamable HTTP only (no local STDIO, no SSE). It does not require authentication but enforces rate limiting.

If your client supports only local STDIO, you can use a local MCP wrapper such as the mcp-remote package.

Endpoint:

https://docs.commercetools.com/apis/mcp

A typical local name for the server is commercetools-dev-content.

Using Developer MCP

When modifying any codebase that changes which commercetools data is used, manually add the commercetools-graphql-schemata tool to the context.
When working in a TypeScript codebase, manually add the prompts tool when implementing new functionality.

Resources provided

Documentation content: find relevant content and receive it as plain text (Markdown).
Natural language descriptions of commercetools API types and endpoints.
GraphQL schemata split into consumable parts.
A selection of prompts showing how to set up a TypeScript application for working with the commercetools GraphQL API.

Tools and prompts

Many client tools currently support only tools, not prompts or resources. Therefore, this server also provides prompts as a tool, allowing your IDE to autonomously request specific explanations.

commercetools-documentation

The commercetools-documentation tool retrieves documentation snippets semantically similar to the provided input text.

Arguments:

Name	Required/Optional	Description
`input`	Required	The query text used to find similar content in the documentation.
`crowding`	Optional	Maximum number of results returned from a single document type. Helps avoid over-representation of content from the same type.
`limit`	Optional	Maximum total number of similar content items to return across all document types.
`contentTypes`	Optional	Array of types to be returned. Allowed values: `apiType`,`apiEndpoint`,`referenceDocs`,`guidedDocs`,`userDocs`.
`products`	Optional	Array of product names to filter the search results. Allowed values: `['Composable Commerce', 'Frontend', 'Checkout', 'Connect']`. For example, `['Composable Commerce', 'Checkout']`.

Defaults

Defaults are optimized for GraphQL client development and balance the likelihood of:

Excluding content with contentType set to apiEndpoint or userDocs unless explicitly requested.
Excluding content with typeNamePostfix ending in Action or Draft unless explicitly requested.
Setting crowding to 5 and limit to 10 (meaning up to 5 results of the same type within 10 total results). When requesting only one specific contentType, set crowding and limit to the same value.

Returned documentation content averages 500-600 tokens in size.

commercetools-graphql-schemata

The commercetools-graphql-schemata tool fetches a partial commercetools GraphQL schema for a specified resource. The schema is self-contained and valid for everything regarding that resource. It includes descriptions but omits implements interface information and deprecated query types.

Arguments

resourceName (required): The commercetools resource name for which to retrieve the GraphQL schema. Example: resourceName: "Product".

commercetools-oas-schemata

The commercetools-oas-schemata tool allows you to fetch a partial commercetools Open Api Spec for a given commercetools resource. The schema is self-contained and valid for everything regarding that resource.

Arguments

resource (required): The name of the commercetools resource for which you want to retrieve the Open Api Spec.
apiKey (required): The name of the commercetools apiKey where the resource is. The server can infer api keys if this is left out of the prompt. Be sure to be specific.

For example, to retrieve the schema for a specific resource, such as Product, pass resource: "Product", apiKey: "API".

commercetools-prompts

The commercetools-prompts tool provides prompts to assist development with the commercetools GraphQL API.

Arguments

Name	Required/Optional	Description
`prompt`	Required	The name of the prompt to retrieve.
`userWish`	Optional	A free-form description of the functionality to be added. This is usually the user's last input. Only applicable for the `add-new-graphql-query-with-typescript` prompt.

Available prompts

Prompts are not supported by all client applications.

set-up-graphql-with-typescript: Step-by-step guide for adding graphql-codegen-based type-safe commercetools GraphQL access using the official TypeScript SDK client. Returns a static response.
add-new-graphql-query-with-typescript: Step-by-step instructions for generating a new or changed GraphQL query robustly, assuming setup follows the set-up-graphql-with-typescript prompt. Takes one optional parameter, userWish, a free-form description of the functionality to be added.

Configure Visual Studio Code and GitHub Copilot

Add the following to your user settings in the MCP section or to a per-workspace .vscode/mcp.json configuration:

  "commercetools-developer": {
    "type": "http",
    "url": "https://docs.commercetools.com/apis/mcp"
  },

These become available in Copilot Agent mode, which can then use them automatically.

You can also manually add these tools as context in Ask, Edit, and Agent modes to "force" Copilot to utilize the selected tools. For example, TypeScript how-to prompts often are not picked up autonomously by Agent mode.

The autogenerated type and schema files in src/ct-graphql/generated (if configured as the graphql-codegen output path) tend to be very large and may slow down the agent significantly if picked up. You can use ignore files or plugins (Cursor has this built in) to exclude that path.

Automatic instructions injection

To make instructions on working with commercetools GraphQL generally available to your workspace in a robust way, save the output of the add-new-graphql-query-with-typescript prompt as .github/instructions/commercetools-graphql.instructions.md with the following YAML frontmatter, which instructs Copilot to pick up these instructions when working on certain files:

In this scenario, you can deselect the commercetools-prompts tool in Copilot to avoid conflicting or duplicate prompts.

---
applyTo: 'src/ct-graphql/**/*.ts'
---

... prompt content here ...

You can view some example prompts for the following use cases:

Prompt files to pick manually

You can also provide prompting content as prompt files in .github/prompts/commercetools-graphql.prompt.md with frontmatter referencing tools to include:

---
mode: 'agent'
tools: ['commercetools-documentation', 'commercetools-graphql-schemata']
---

... prompt content here like in instructions...

Rate limiting

This server enforces rate limiting to protect against abuse. Each IP address is limited to 100 requests per 15 minutes. Exceeding this limit results in a 429 error.

Build your own MCP server

Use the commercetools documentation similarity search API

You can build your own commercetools-documentation-search tool by leveraging the public similarity search REST endpoint. Make a GET request to the following endpoint:

https://docs.commercetools.com/apis/rest/content/similar-content

Query parameters

You can customize your API request by providing the following query parameters:

Name	Required/Optional	Description
`input`	Required	The search query.
`limit`	Optional	Maximum number of results to return.
`crowding`	Optional	Maximum number of results per `contentType`.
`contentTypes`	Optional, Repeatable	Filter by `contentType`. Possible values: `apiType`, `apiEndpoint`, `referenceDocs`, `guidedDocs`, `userDocs`
`products`	Optional, Repeatable	Filter by product. Possible values: `Composable Commerce`, `Frontend`, `Checkout`, `Connect`

Example request

The following example searches for documentation similar to product variant, limits results to 5, allows a maximum of 3 results per contentType, and restricts the contentTypes to apiType and referenceDocs for the product Composable Commerce.

https://docs.commercetools.com/apis/rest/content/similar-content?input=product%20variant&limit=5&crowding=3&contentTypes=apiType&contentTypes=referenceDocs&products=Composable%20Commerce

The response is a JSON object containing an array of similar content items with metadata such as title, contentType, URL, and token count. The following is the TypeScript type definition of the response:

type TVectorSearchResult = {
  count: number; // total number of similar content items found
  similarContent: Array<{
    id: string; // identifier for the content
    content: string; // docs content
    metadata: {
      contentType: string; // eg. 'apiType'
      url: string; // eg. 'https://docs.commercetools.com/api/projects/me-shoppingLists#ctp:api:type:MyShoppingListDraft'
      urn: string; // eg. 'ctp:api:type:MyShoppingListDraft' (on content that is not a webpage)
      title: string; // eg. '"MyShoppingListDraft" data representation in the Composable Commerce API'
      typeName: string; // eg. 'MyShoppingListDraft' (on REST API types)
      api: string; // which API-spec it belongs to eg. 'api' (on REST API types and endpoints)
      apiTitle: string; // eg. 'commercetools Composable Commerce API' (on REST API types and endpoints)
      products: string[]; // eg. ['Composable Commerce']
      tokenCount: number; // eg. 335  how big is the content
      codeRemoved: boolean; // eg. true  .. did we strip out code snippets from it or not because it was too big for example
    };
    distance: number; // vector distance. This is an unscaled number, do not try to infer information from the absolute or relative amount that goes beyond the ordering of the returned items.
  }>;
};

How to use in your own MCP server

In the following example, the query searches for documentation similar to product variant, limits the results to 5, allows a maximum of 3 results per contentType, and restricts the contentTypes to apiType and referenceDocs for the product Composable Commerce.

How to use in your own MCP servertypescript

const params = new URLSearchParams({
  input: 'product variant',
  limit: '5',
  crowding: '3',
  contentTypes: 'apiType',
});
params.append('contentTypes', 'referenceDocs');
params.append('products', 'Composable Commerce');

const response = await fetch(
  `https://docs.commercetools.com/apis/rest/content/similar-content?${params.toString()}`
);
const data = await response.json();

This allows you to build your own documentation search tool, integrate semantic documentation search into your custom MCP server implementation, or use in any other tool that looks for information about commercetools.

Fetch content by ID

The IDs for GraphQL schemata, REST endpoints (natural language) and REST types (natural language) follow a custom URN style shape. To fetch one ID, include the id query parameter in a GET request to the following endpoint:

Example GET request with a single id query parametershell

curl -X GET "https://docs.commercetools.com/apis/rest/content/by-id?id=ctp:api:type:MyShoppingListDraft"

To fetch multiple IDs, make a POST request to the same endpoint with a JSON body containing an array of IDs:

Example POST request with a JSON body containing multiple idsshell

curl -X POST "https://docs.commercetools.com/apis/rest/content/by-id" \
     -H "Content-Type: application/json" \
     -d '{"ids": ["ctp:api:type:MyShoppingListDraft", "ctp:api:type:Product", "ctp:api:type:Order"]}'

The IDs for documentation pages follow their path structure but due to the chunking algorithm being dynamic it is not recommended to assume any URL path is present. You should use the similarity search to find documentation content.

Developer MCP

MCP Server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Using Developer MCP.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Resources provided.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Tools and prompts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

commercetools-documentation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Defaults.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

commercetools-graphql-schemata.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Arguments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

commercetools-oas-schemata.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Arguments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

commercetools-prompts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Arguments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Available prompts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Configure Visual Studio Code and GitHub Copilot.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Automatic instructions injection.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Prompt files to pick manually.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Rate limiting.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Build your own MCP server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query parameters.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Example request.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

How to use in your own MCP server.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Fetch content by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

MCP Server

Using Developer MCP

Resources provided

Tools and prompts

commercetools-documentation

Defaults

commercetools-graphql-schemata

Arguments

commercetools-oas-schemata

Arguments

commercetools-prompts

Arguments

Available prompts

Configure Visual Studio Code and GitHub Copilot

Automatic instructions injection

Prompt files to pick manually

Rate limiting

Build your own MCP server

Query parameters

Example request

How to use in your own MCP server

Fetch content by ID