Knowledge MCP

Ask about this Page
Copy for LLM
View as Markdown

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

The Knowledge Model Context Protocol (MCP) provides a set of specialized tools that enable AI agents and IDEs to interact with commercetools documentation and APIs. By connecting to the Knowledge MCP server, you can leverage AI to accelerate your development workflow, from understanding concepts and ad-hoc interactions to implementing features. For a deeper dive into the protocol itself, see the official specification at modelcontextprotocol.io.

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

Which tool should I use?

The Knowledge MCP provides a suite of tools for different tasks. Use this guide to select the right tool for your needs.

If you want to...Use this tool...
Find documentation for a concept or feature.commercetools-documentation-search
Get the GraphQL schema for a specific commercetools resource.commercetools-graphql-schemata
Get the OpenAPI Specification (OAS) for a specific commercetools resource.commercetools-oas-schemata
Validate a GraphQL query or mutation against the commercetools GraphQL schema.commercetools-graphql-validate
The server also exposes a prompt — commercetools-developer-tips — that loads commercetools-specific conventions and patterns. See Available prompts for details.

GraphQL Feature Implementation

This workflow can be used when you need to implement a new feature using the GraphQL API.

  1. Discover with commercetools-documentation-search: Start by searching for the feature or concept you want to implement. This will give the agent the conceptual understanding and business behavior definitions, and hints to which are the relevant API resources for the described scenario.
    • Example input: "How to create a cart with an initial product?"
  2. Explore Schema with commercetools-graphql-schemata: Once the agent has identified the resource (for example Cart), it can fetch its GraphQL schema to understand its fields, types, and available mutations.
    • Example resourceName: "Cart"
  3. Validate with commercetools-graphql-validate: Before running the query, validate it against the full commercetools GraphQL schema to catch hallucinated fields, incorrect argument types, or missing required fields.
    • Example query: "mutation { createCart(draft: { currency: \"EUR\" }) { id version } }"
  4. Generate Code or execute: With a clear understanding of the API and schema, and a validated query, the agent can now create the GraphQL query or mutation in the application code, or directly execute it as an ad-hoc operation.

REST API Interaction

Use this workflow when you need to interact with the commercetools REST API.

  1. Find Endpoint with commercetools-documentation-search: Search the documentation to find the correct REST endpoint and HTTP method for your task.
    • Example input: "update customer details"
  2. Get Specification with commercetools-oas-schemata: Fetch the OpenAPI Specification for the resource to see the detailed request/response structure, parameters, and update actions.
    • Example resourceName: "Customer"
  3. Generate Code or execute: The agent can now construct and execute the HTTP request in your application or as an ad-hoc operation, ensuring the payload matches the specification.

Ad-hoc Queries and Exploration

For quick, ad-hoc queries or exploration of the documentation and APIs, you can use the tools in a more flexible manner:

  1. Quick Search with commercetools-documentation-search: Use this tool to find relevant documentation for any topic or question you have.
    • Example input: "What is the difference between a Product and a ProductProjection?"
  2. Deep Dive with Schema Tools: If the documentation points to specific resources, you can immediately fetch their GraphQL schema or OpenAPI Specification to get a deeper understanding of their structure and capabilities.
    • Example resourceName: "ProductProjection" for either GraphQL or REST.

Project Scaffolding and One-Time Actions

This workflow is ideal for bootstrapping a new project or performing one-time setup tasks, like configuring Checkout.

  1. Discover with commercetools-documentation-search: Start by searching for high-level guides or tutorials related to your goal. This provides the necessary context and outlines the required resources and sequence of operations.
    • Example input: "How to set up Checkout" or "Getting started with the Frontend SDK"
  2. Explore Schema with commercetools-graphql-schemata or commercetools-oas-schemata: Based on the documentation, identify the core API resources involved (for example, Cart, Order, Payment). Fetch their schemata to understand the fields and relationships required for the setup.
    • Example resourceName: "Cart", "Order"
  3. Generate Code or execute: With a clear understanding of the steps and data models, the agent can generate the necessary scaffolding code for your project or execute the sequence of one-time API calls to configure the feature.
These workflows provide a structured approach to leveraging the MCP tools, moving from high-level concepts to concrete implementation details for both development and ad-hoc interactions. For more detailed examples of these workflows in action, see the End-to-End Examples section below.

MCP Server

The server is accessible via streamable HTTP only (no local STDIO, no SSE). It does not require authentication but enforces rate limiting.
Endpoint:
https://docs.commercetools.com/apis/mcp
A typical local name for the server is commercetools-knowledge.

Available tools

commercetools-documentation-search

The commercetools-documentation-search tool retrieves documentation snippets semantically similar to the provided input text.
Arguments:
NameRequired/OptionalDescription
inputRequiredThe query text used to find similar content in the documentation.
crowdingOptionalMaximum number of results returned from a single document type. Helps avoid over-representation of content from the same type.
limitOptionalMaximum total number of similar content items to return across all document types.
contentTypesOptionalArray of types to be returned. Allowed values: apiType,apiEndpoint,referenceDocs,guidedDocs,userDocs, otherDocsPage.
productsOptionalArray of product names to filter the search results. Allowed values: ['Composable Commerce', 'Frontend', 'Checkout', 'Connect', 'InStore']. 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".
The available resourceName values are discoverable by MCP clients that support dynamic enums.

commercetools-oas-schemata

The commercetools-oas-schemata tool allows the agent 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. It does not contain the schema information for reference expansion - if a client wants to use reference expansion it has to read the schema of the expanded resource separately, or use the fully typed commercetools SDKs in the codebase.

Arguments

  • resourceName (required): The commercetools resource for which you want to retrieve the Open Api Spec. Example: resourceName: "CartDiscount".
For example, to retrieve the schema for a specific resource, such as a checkout Application, pass resourceName: "Application".
The available resourceName values are discoverable by MCP clients that support dynamic enums.

commercetools-graphql-validate

The commercetools-graphql-validate tool validates a GraphQL query or mutation against the commercetools GraphQL schema. It detects hallucinated fields, incorrect argument types, and missing required fields before the query is executed, helping to catch errors in AI-generated code.
The tool parses the input with graphql-js and validates it against the commercetools SDL schema, which is loaded at server initialization.

Arguments

NameRequired/OptionalDescription
queryRequiredThe GraphQL query or mutation string to validate.

Response

When the query is valid, the tool returns:

{ "valid": true }

When the query is invalid, the tool returns a list of actionable errors with their location:

{
  "valid": false,
  "errors": [
    {
      "message": "Cannot query field \"foo\" on type \"Cart\".",
      "line": 3,
      "column": 5
    }
  ]
}

This tool is read-only and does not execute the query against any commercetools Project. The query is validated against the public commercetools schema and NOT against the user's specific projects or its configurations.

Available prompts

In addition to tools, the Knowledge MCP exposes a prompt that you can invoke explicitly to load commercetools-specific guidance into your AI agent's context. Unlike tools (which an agent calls automatically when relevant), prompts are user-invoked through the client's UI.

commercetools-developer-tips

The commercetools-developer-tips prompt loads commercetools-specific conventions and best practices for working with the REST and GraphQL APIs.

It covers:

  • Cross-cutting conventions: key vs id, centAmount minor units, LocalizedString, in-store APIs, multi-action update requests, ISO 8601 date formatting
  • Query predicates (where clauses) with examples
  • Sort clauses
  • REST API tips (version field, pagination, expand)
  • GraphQL tips (stubbed types, schema scope)
  • Common pitfalls

When to invoke

Invoke the prompt at the start of a coding session that involves writing commercetools queries, mutations, or REST update actions. The prompt content is loaded once into the agent's context and informs subsequent tool calls. Re-invoke if you start a new session or want to refresh the context.

IDE and Client Setup

You can connect to the Knowledge MCP server from any MCP-compatible client.

Visual Studio Code

Add the following to your user mcp settings (mcp.json) or a per-workspace .vscode/mcp.json configuration:
"commercetools-knowledge": {
  "type": "http",
  "url": "https://docs.commercetools.com/apis/mcp"
}
For more details, see the Visual Studio Code documentation.
The tools become available in Copilot Chat, which can then use them automatically. You can also manually add these tools as context using the @ mention to "force" Copilot to utilize them.

Cursor

In Cursor, go to Cursor settings > Tools & MCP > New MCP Server and add a new server configuration:
"commercetools-knowledge": {
  "type": "http",
  "url": "https://docs.commercetools.com/apis/mcp"
}
For more details, see the Cursor documentation.

Claude

On Claude Desktop App, navigate to Customize > Connectors > Add custom connector. Now you should see a panel where you can enter the details of the MCP server.
Name: commercetools-knowledge
Remote MCP Server URL: https://docs.commercetools.com/apis/mcp

For Claude Code, connect the MCP server via the command-line interface:

claude mcp add --transport http commercetools-knowledge https://docs.commercetools.com/apis/mcp
For more details, see the Claude documentation.

JetBrains IDEs

For JetBrains IDEs (IntelliJ, WebStorm, etc.), you can use a compatible plugin that supports MCP, such as the AI Assistant, and configure it to connect to the server endpoint. Configuration details vary by plugin.

Generic Clients

For any other client that supports MCP via local STDIO, use the mcp-remote package as a wrapper.
"commercetools-knowledge": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://docs.commercetools.com/apis/mcp"]
}

Rate limiting

This server enforces rate limiting to protect against abuse. Each IP address is limited to 100 requests per 15 minutes.
429 Response Examplehttp
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: <seconds-until-reset>
Retry-After: <seconds-until-reset>
Content-Type: text/html; charset=utf-8

Too many requests from this IP, please try again after 15 minutes
  • Exceeding this limit results in a 429 Too Many Requests HTTP error.
  • The response includes a Retry-After header indicating how many seconds to wait before making a new request.
  • The REST API and MCP server share the same rate limit.
  • For heavy usage or enterprise needs, consider building your own MCP server.

Troubleshooting

  • 429 Errors: You have exceeded the rate limit. Check the Retry-After header and wait the specified time before retrying.
  • Empty Results: If a search returns no results, try rephrasing your input to be more specific or broader. Check that your contentTypes and products filters are not too restrictive.
  • Invalid Resource Names: If you receive an error for an invalid resourceName with commercetools-graphql-schemata, ensure the name is spelled correctly and exists. MCP-enabled clients can discover the available enum of resource names.
  • Latency: The server is located in europe-west1. Users in other regions may experience higher latency.

End-to-End Examples

This section provides practical examples that demonstrate how the Knowledge MCP tools can be used, aligning with the recommended workflows.

GraphQL Feature Implementation

This example demonstrates how to add a product to a cart using the GraphQL API.

1. Discover with commercetools-documentation-search

First, the agent needs to find out how to add an item to a cart. It uses the commercetools-documentation-search tool to search for relevant documentation.
Agent Request:
{
  "tool": "commercetools-documentation-search",
  "query": "add product to cart"
}
Agent Response (summary):
The search results point to the addLineItem update action on a Cart. It also mentions that the agent needs the cartId, version, sku, and quantity.

2. Explore Schema with commercetools-graphql-schemata

Now that the agent knows it needs to work with Carts, it can fetch the GraphQL schema for the Cart resource to understand its structure and available mutations.
Agent Request:
{
  "tool": "commercetools-graphql-schemata",
  "resourceName": "Cart"
}
Agent Response (summary):
The agent receives the GraphQL schema for the Cart type, including fields like lineItems, totalPrice, and available update actions like addLineItem.

3. Generate Code or execute

With a clear understanding of the API and schema, the agent can now construct the code to create a cart with an initial product.

This workflow—discover, get schema, and implement—is a powerful way to use the Knowledge MCP to accelerate development.

REST API Interaction

This example shows how to update a customer's email address using the REST API.

1. Find Endpoint with commercetools-documentation-search

First, the agent searches the documentation to find out how to update a customer's email.

Agent Request:
{
  "tool": "commercetools-documentation-search",
  "query": "update customer email"
}
Agent Response (summary):
The documentation indicates that the agent should send a POST request to the /{projectKey}/customers/{ID} endpoint with an update action of changeEmail.

2. Get Specification with commercetools-oas-schemata

Next, the agent fetches the OpenAPI Specification for the Customer resource to understand the exact request and response structure.
Agent Request:
{
  "tool": "commercetools-oas-schemata",
  "resourceName": "Customer"
}
Agent Response (summary):
The agent receives the OpenAPI specification for the Customer-write resource, detailing the available endpoints, methods, parameters, and the schema for the Update actions, including changeEmail.

3. Generate Code or execute

With the endpoint and specification understood, the agent can now write the code to make a POST request to the commercetools API, including the correct version and action payload to update the customer's email.

This workflow demonstrates how to combine documentation search with API specifications to interact with the commercetools REST API.

Ad-hoc Queries and Exploration

This example illustrates how to search for products with a specific attribute using a GraphQL query.

1. Quick Search with commercetools-documentation-search

First, the agent needs to understand how to filter products. It can search the documentation for guidance.

Agent Request:
{
  "tool": "commercetools-documentation-search",
  "query": "filter products by attribute"
}
Agent Response (summary):
The documentation suggests using the productProjections query and applying a where predicate to filter the results. It provides examples of how to structure the where clause for attributes.

2. Deep Dive with commercetools-graphql-schemata

To build the query correctly, the agent needs to know the structure of a ProductProjection. It can fetch its GraphQL schema if necessary.
Agent Request:
{
  "tool": "commercetools-graphql-schemata",
  "resourceName": "ProductProjection"
}
Agent Response (summary):
The agent receives the GraphQL schema for ProductProjection, which includes fields like masterVariant, variants, and their attributes. This confirms the fields to use in the query.

3. Writing the search query

With a clear understanding of the filtering mechanism and the data schema, the agent can now construct the final GraphQL query to find products with a specific attribute.

This workflow shows how to go from a general goal (searching products) to a specific, executable API query by combining documentation and schema information.

Project Scaffolding: Setting up Checkout

This example demonstrates how to set up a checkout by identifying the necessary API resources and their interactions.

1. Discover with commercetools-documentation-search

The agent starts by searching for a high-level guide on setting up Checkout.

Agent Request:
{
  "tool": "commercetools-documentation-search",
  "query": "How to set up Checkout?"
}
Agent Response (summary):
The documentation outlines the setup process, which includes granting permissions, creating API clients, installing payment connectors, and creating Checkout Applications. It identifies Application and PaymentIntegration as core resources for Checkout.

2. Explore Schema with commercetools-oas-schemata

Based on the guide, the agent fetches the OpenAPI Specification for the identified resources to understand their fields and relationships.

Agent Request (for each resource):
{
  "tool": "commercetools-oas-schemata",
  "resourceName": "Application"
}

{
  "tool": "commercetools-oas-schemata",
  "resourceName": "PaymentIntegration"
}
Agent Response (summary):
The agent gathers the OpenAPI specifications for Application and PaymentIntegration, learning about the endpoints to create and configure them, and the required fields for each.

3. Generate Code or execute

With a clear map of the required resources and their interactions, the agent can now generate the initial project files and boilerplate code for a Checkout service, including functions for each step of the setup flow, such as creating a Checkout Application and configuring payment integrations.

This workflow is effective for bootstrapping projects and ensuring all necessary API interactions are accounted for from the start.

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:

NameRequired/OptionalDescription
inputRequiredThe search query.
limitOptionalMaximum number of results to return.
crowdingOptionalMaximum number of results per contentType.
contentTypesOptional, RepeatableFilter by contentType.
Possible values: apiType, apiEndpoint, referenceDocs, guidedDocs, userDocs, otherDocsPage
productsOptional, RepeatableFilter by product.
Possible values: Composable Commerce, Frontend, Checkout, Connect, InStore

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.

Privacy policy

Please refer to commercetools Privacy Notice page.

Support

For any issue related to using the MCP server, please report it through the commercetools support portal.