Developer MCP

Provides commercetools documentation APIs for developers (MCP Server, Content API)

Developers IDEs or AI Agents can connect to a public MCP server that provides tools helping with effectively building commerce solutions that leverage commercetools products.

Developers building their own MCP servers or AI applications that work with commercetools documentation content and/or API references can access plain text (Markdown) natural language 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 available through streamable HTTP only (no local STDIO, no SSE). It does not require authentication but it is rate limited.

If your client only supports local STDIO, a local MCP wrapper can be used. For example, the mcp-remote package at https://www.npmjs.com/package/mcp-remote

Endpoint:

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

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

Using the MCP server

In practice:

on any codebase, when doing modifications that change the selection of data needed from commercetools, to manually add the commercetools-graphql-schemata tool to the context.
when developing on a TypeScript codebase, we recommend manually adding the prompts tool to the context when adding new functionality.

Resources provided

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

Available tools

Many client tools currently only support "tools" but not "prompts" or "resources." This is why this server provides the prompts as a tool, too so that your IDE can autonomously request specific general explanations.

commercetools-documentation

The commercetools-documentation tool retrieves documentation snippets that are 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	The maximum number of results to return from a single document type. Helps to avoid over-representation of content from the same type.
`limit`	Optional	The maximum total number of similar content items to return across all document types.
`contentTypes`	Optional	An array of types to be returned. Allowed values are `apiType`,`apiEndpoint`,`referenceDocs`,`guidedDocs`,`userDocs`.
`products`	Optional	An array of product names to filter the search results. Allowed values are `['Composable Commerce', 'Frontend', 'Checkout', 'Connect']`. For example, `['Composable Commerce', 'Checkout']` to restrict results to specific products.

Defaults

commercetools-documentation defaults are targeting a GraphQL client development use case and are balancing likelihood of:

Content with contentType set to apiEndpoint or userDocs is excluded unless explicitly requested
Content with typeNamePostfix ending in Action or Draft is excluded unless explicitly requested
crowding: 5, limit: 10 (that is, of the 10 contents provided, up to 5 will be of the same type). If you are requesting only one specific contentType, pass the same value for crowding and limit.

The mean size of documentation content returned is in the range of 500-600 tokens.

commercetools-graphql-schemata

The commercetools-graphql-schemata tool allows you to fetch a partial commercetools GraphQL schema for a given commercetools resource. The schema is self-contained and valid for everything regarding that resource. It contains descriptions but no implements interface information and no deprecated query types.

Arguments

resourceName (required): The name of the commercetools resource for which you want to retrieve the GraphQL schema.

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

commercetools-prompts

The commercetools-prompts tool provides a set of prompts to help you develop 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, typically 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: A step-by-step explanation of how to add graphql-codegen-based type-safe commercetools GraphQL access to a project, leveraging the TypeScript SDK's robust and officially supported client library. Takes no parameters and returns a static response.
add-new-graphql-query-with-typescript: A step-by-step instruction on how to generate a new or changed GraphQL query to the codebase in a robust way. Assumes the setup follows the instructions of the set-up-graphql-with-typescript prompt. Takes one optional parameter userWish, which is 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 in a per workspace .vscode/mcp.json configuration.

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

They are then available to Agent mode for Copilot to autonomously decide to use them.

The tools are also available to be added as context by you manually in Ask, Edit, and Agent mode. This "forces" Copilot to make use of the tools you chose to add. For example, the provided TypeScript how-to prompts are often not picked up autonomously by Agent mode.

The autogenerated type and schema files in src/ct-graphql/generated (if that path is configured for graphql-codegen output) tend to be so large that they slow down the agent significantly if it picks them up. You can use various ways (for example, a plugin) to ignore that path via an ignore file. Cursor has such functionality built in.

Automatic instructions injection

A more customizable and robust way to making the instructions how to work with commercetools GraphQL in general available to your workspace is to take the output of the add-new-graphql-query-with-typescript prompt and save it as .github/instructions/commercetools-graphql.instructions.md with an applyTo yaml frontmatter that instructs Copilot to generally pick up this instructions when working on certain files.

In this scenario, you can deselect the commercetools-prompts tool in Copilot to not get 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

A similar setup can be achieved by providing such prompting content as prompt files in .github/prompts/commercetools-graphql.prompt.md. Prompt files also support frontmatter, in their case the frontmatter is referencing tools to be included in the chat.

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

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

Rate limiting

This server implements rate limiting to protect against abuse. Each IP address is limited to 100 requests per 15 minutes. If you exceed this limit, you will receive 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 provided by commercetools. Make a GET request to the following endpoint to perform semantic search over documentation content.

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

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.

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, each 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

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 content returned by the similarity search can also be fetched standalone by ID.

The URL is https://docs.commercetools.com/apis/rest/content/by-id

A GET request takes one query parameter id.
A POST request takes a JSON object with an array of IDs formed like {"ids": ["id-1", "id-2", "id-3" ]}

The IDs for GraphQL schemata, REST Endpoints (natural language) and REST types (natural language) follow a well defined custom URN style shape (try a similarity search request to see it).

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 the 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;}

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;}

Available tools.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-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 the MCP server

Resources provided

Available tools

commercetools-documentation

Defaults

commercetools-graphql-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