# Knowledge MCP

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](https://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` |
| Fetch a specific documentation entry when you know its content ID. | `commercetools-documentation-by-id` |
| 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` |
| Validate a REST request against the commercetools OpenAPI specifications. | `commercetools-rest-validate` |

The server also exposes a prompt — `commercetools-developer-tips` — that loads commercetools-specific conventions and patterns. See [Available prompts](/dev-tooling/mcp/knowledge-mcp.md#available-prompts) for details.

## Recommended Workflows

The Knowledge MCP tools are designed to be used in sequence to generate API interactions with the commercetools APIs, either for developing a solution or for ad-hoc interactions. Here are some recommended sequences:

### 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`**: `"api-Customer-write"`
3. **Validate with `commercetools-rest-validate`**: Before sending the request, validate the HTTP method, path, and request body against the OpenAPI specification to catch invalid paths, unsupported methods, or payload mistakes.
   - **Example input**: `method: "POST"`, `path: "/my-project/customers/12345"`, `apiKey: "api-Customer-write"`, `body: "{ \"version\": 3, \"actions\": [{ \"action\": \"changeEmail\", \"email\": \"user@example.com\" }] }"`
4. **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. **Fetch a specific documentation entry**: If the search result returns the content ID you need, fetch that entry directly to inspect its full raw content.
   - **Example `id`**: `"ctp:api:type:ProductProjection"`
3. **Deep Dive with Schema Tools**: If the documentation points to specific resources, you can fetch their GraphQL schema or OpenAPI Specification to get a deeper understanding of their structure and capabilities.
   - **Example `resourceName`**: `"ProductProjection"` for GraphQL or `"api-ProductProjection"` for 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"` for GraphQL or `"checkout-Application"` for REST.
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](/dev-tooling/mcp/knowledge-mcp.md#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](/dev-tooling/mcp/knowledge-mcp.md#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

| 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`, `otherDocsPage`, `Skill`. |
| `products` | Optional | Array 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.

To include only Skill reference content, set `contentTypes` to `Skill`. To exclude Skill reference content, add `Skill` to `excludeContentTypes`. This filter applies to the Skill content type as a group, not to individual skills.

Returned documentation content averages 500-600 tokens in size.

#### commercetools-documentation-by-id

The `commercetools-documentation-by-id` tool fetches a single documentation entry by its content ID. Use it when you know the ID, from a previous search result, and want the full raw content for that entry.

##### Arguments

- `id` (required): The documentation entry ID to retrieve. Example: `id: "ctp:api:type:Product"`.

This tool is useful after `commercetools-documentation-search` when you want to inspect one exact result instead of working from summarized search snippets.

#### 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: "api-CartDiscount"`.

For example, to retrieve the schema for a specific resource, such as a checkout `Application`, pass `resourceName: "checkout-Application"`.

The available `resourceName` values are discoverable by MCP clients that support dynamic enums.

#### commercetools-rest-validate

The `commercetools-rest-validate` tool validates REST API requests against the commercetools OpenAPI specifications before you send them. It helps catch invalid paths, unsupported methods, missing request bodies, and schema mismatches in AI-generated requests.

##### Arguments

| Name | Required/Optional | Description |
| --- | --- | --- |
| `method` | Required | HTTP method for the request. Allowed values: `GET`, `POST`, `DELETE`, `PATCH`, `PUT`, `HEAD`. |
| `path` | Required | Request path including the Project key as the first segment. Example: `/my-project/products`. |
| `body` | Optional | Request body as a JSON string. Required for `POST`, `PATCH`, and `PUT` requests that expect a body. |
| `apiKey` | Required | API identifier. Use API names such as `api`, `import`, or `checkout`, or use a resource-specific key when needed. |

Use this tool after `commercetools-oas-schemata` and before executing a REST request.

#### 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

| Name | Required/Optional | Description |
| --- | --- | --- |
| `query` | Required | The GraphQL query or mutation string to validate. |

##### Response

When the query is valid, the tool returns:

```json
{ "valid": true }
```

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

```json
{
  "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:

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

For more details, see the [Visual Studio Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server).

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:

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

For more details, see the [Cursor documentation](https://cursor.com/docs/mcp#using-mcpjson).

### Claude

#### 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
```

#### Claude Code

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

```bash
claude mcp add --transport http commercetools-knowledge https://docs.commercetools.com/apis/mcp
```

For more details, see the [Claude documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp#h_3d1a65aded).

### 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.

```json
"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**.

```http title="429 Response Example"
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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "tool": "commercetools-oas-schemata",
  "resourceName": "api-Customer-write"
}
```

**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. Validate with `commercetools-rest-validate`

Before sending the request, the agent validates the REST request against the OpenAPI specification.

**Agent Request:**

```json
{
  "tool": "commercetools-rest-validate",
  "method": "POST",
  "path": "/my-project/customers/12345",
  "apiKey": "api-Customer-write",
  "body": "{ \"version\": 3, \"actions\": [{ \"action\": \"changeEmail\", \"email\": \"user@example.com\" }] }"
}
```

**Agent Response (summary):**

The validation confirms whether the request path, method, and update payload match the commercetools API definition before the request is executed.

#### 4. 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:**

```json
{
  "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:**

```json
{
  "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 request 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:**

```json
{
  "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):**

```json
{
  "tool": "commercetools-oas-schemata",
  "resourceName": "checkout-Application"
}
```

```json
{
  "tool": "commercetools-oas-schemata",
  "resourceName": "checkout-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

### Documentation search tool

`GET /tools/documentation-search`

Retrieves documentation snippets semantically similar to the provided input text.

**Query parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `query` | Required | The search query. |
| `limit` | Optional | Maximum number of results to return. Default: `10`. |
| `crowding` | Optional | Maximum number of results per `contentType`. Default: `5`. |
| `contentTypes` | Optional, Repeatable | Filter by `contentType`. Allowed values: `apiType`, `apiEndpoint`, `referenceDocs`, `guidedDocs`, `userDocs`, `otherDocsPage`, `Skill`. Default: `referenceDocs`, `guidedDocs`, `userDocs`. |
| `excludeContentTypes` | Optional, Repeatable | Content types to exclude. |
| `products` | Optional, Repeatable | Filter by product. Allowed values: `Composable Commerce`, `Frontend`, `Checkout`, `Connect`, `InStore`, `AI Hub`. Default: `Composable Commerce`, `Checkout`, `Connect`. |
| `excludeProducts` | Optional, Repeatable | Product names to exclude. |

Use `contentTypes=Skill` to return only Skill reference pages. Use `excludeContentTypes=Skill` to exclude them from mixed-result searches. These parameters filter the Skill content type as a group, not individual skills.

**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/tools/documentation-search?query=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:

```typescript
type TVectorSearchResult = {
  count: number; // total number of similar content items found
  similarContent: Array<{
    id: string; // identifier for the content
    content: string; // docs content
    metadata: {
      title: string; // eg. '"MyShoppingListDraft" data representation in the Composable Commerce API'
      url: string; // eg. 'https://docs.commercetools.com/api/projects/me-shoppingLists#ctp:api:type:MyShoppingListDraft'
      contentType: string; // eg. 'apiType'
      additionalPaths: string[]; // additional URLs for the same content
      previousChunk: string | null; // previous chunk of content, if any
      nextChunk: string | null; // next chunk of content, if any
      similarityScore: number; // similarity score between 0 and 1, higher is more similar
    };
    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.
  }>;
};
```

**TypeScript example:**

```typescript title="Documentation search"
const params = new URLSearchParams({
  query: 'add product to cart',
  limit: '5',
  crowding: '3',
});
params.append('contentTypes', 'apiEndpoint');
params.append('contentTypes', 'referenceDocs');
params.append('products', 'Composable Commerce');

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

### Documentation by ID tool

`GET /tools/documentation-by-id`

Fetches a single documentation content entry by its ID. Use this endpoint when you already have a content ID (for example, one returned by the documentation search tool) and want to retrieve the raw content as a string. It corresponds to the `commercetools-documentation-by-id` MCP tool.

**Parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `id` | Required | The ID of the documentation entry to fetch. Typically the identifier returned by the documentation search tool. |

**Example request:**

```bash
curl -s -X GET "https://docs.commercetools.com/apis/rest/tools/documentation-by-id?id=ctp:api:type:MyShoppingListDraft"
```

The response contains the raw content for the requested entry:

```json
{
  "result": "..."
}
```

**TypeScript example:**

```typescript title="Documentation by ID"
const response = await fetch(
  'https://docs.commercetools.com/apis/rest/tools/documentation-by-id?id=ctp:api:type:MyShoppingListDraft'
);
);
const data = await response.json();
```

### GraphQL schemata tool

`GET /tools/graphql-schemata`

Fetches a partial GraphQL SDL for a single commercetools resource. Use this endpoint to inspect fields and available operations before writing queries or mutations. It corresponds to the `commercetools-graphql-schemata` MCP tool.

**Query parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `resourceName` | Required | The commercetools resource name. Representative values: `Cart`, `Product`, `Customer`, `Order`, `ProductProjection`. |

**Example request:**

```bash
curl -s -X GET "https://docs.commercetools.com/apis/rest/tools/graphql-schemata?resourceName=Cart"
```

The response contains the GraphQL SDL fragment for the requested resource:

```json
{
  "result": "type Cart { id: String! version: Int! ... }"
}
```

**TypeScript example:**

```typescript title="GraphQL schemata"
const response = await fetch(
  `https://docs.commercetools.com/apis/rest/tools/graphql-schemata?resourceName=Cart`
);
const data = await response.json();
```

### GraphQL validation tool

`POST /tools/graphql-validate`

Validates a GraphQL query or mutation against the public commercetools GraphQL schema. This is read-only validation — the query is not executed against any project. It corresponds to the `commercetools-graphql-validate` MCP tool.

**Parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `query` | Required | The GraphQL query or mutation string to validate. |

**Example request:**

```bash
curl -s -X POST https://docs.commercetools.com/apis/rest/tools/graphql-validate 
  -H "Content-Type: application/json" 
  -d '{
    "query": "mutation { createCart(draft: { currency: \"EUR\" }) { id version } }"
  }'
```

When the query is valid, the response is:

```json
{ "result": { "valid": true } }
```

When the query is invalid, the response includes a list of actionable errors:

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

**TypeScript example:**

```typescript title="GraphQL validate"
const response = await fetch(
  'https://docs.commercetools.com/apis/rest/tools/graphql-validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: 'mutation { createCart(draft: { currency: "EUR" }) { id version } }',
    }),
  }
);
const data = await response.json();
```

### OpenAPI schemata tool

`GET /tools/oas-schemata`

Fetches a partial OpenAPI schema for a commercetools resource. Use this endpoint when generating REST clients, request payloads, and update actions. It corresponds to the `commercetools-oas-schemata` MCP tool.

**Query parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `resourceName` | Required | The commercetools resource name. Representative values: `api-Cart-read`, `api-Cart-write`, `api-Customer-read`, `api-Customer-write`, `checkout-Application`. |

**Example request:**

```bash
curl -s -X GET "https://docs.commercetools.com/apis/rest/tools/oas-schemata?resourceName=api-Customer-write"
```

The response contains the OpenAPI JSON object for the requested resource:

```json
{
  "result": { "openapi": "3.0.0", "info": { ... }, "paths": { ... } }
}
```

**TypeScript example:**

```typescript title="OpenAPI schemata"
const response = await fetch(
  `https://docs.commercetools.com/apis/rest/tools/oas-schemata?resourceName=api-Customer-write`
);
const data = await response.json();
```

### REST validation tool

`POST /tools/rest-validate`

Validates REST API requests (method, path, and body) against commercetools OpenAPI specifications offline. Use this endpoint to catch errors before making actual API calls. It corresponds to the `commercetools-rest-validate` MCP tool.

The tool checks:

- Path exists in the API.
- HTTP method is allowed for that path.
- Request body matches the expected schema (types, required fields, enums).
- Discriminator fields (like `action` in update requests) are valid.

**Parameters:**

| Name | Required/Optional | Description |
| --- | --- | --- |
| `method` | Required | HTTP method for the request. Allowed values: `GET`, `POST`, `DELETE`, `PATCH`, `PUT`, `HEAD`. |
| `path` | Required | Request path (for example, `/my-project/products`). Include the Project key as the first segment. |
| `body` | Optional | Request body as a JSON string. Required for `POST`, `PATCH`, and `PUT` requests that expect a body. |
| `apiKey` | Required | API identifier. Use the concrete resource key exposed by the tool, such as `api-Customer-write`, `api-Product`, or `checkout-Application`. |

**Example request:**

```bash
curl -s -X POST https://docs.commercetools.com/apis/rest/tools/rest-validate 
  -H "Content-Type: application/json" 
  -d '{
    "method": "POST",
    "path": "/my-project/products",
    "apiKey": "api-Product",
    "body": "{ \"productType\": { \"typeId\": \"product-type\", \"key\": \"standard-product\" }, \"name\": { \"en\": \"New Product\" }, \"slug\": { \"en\": \"new-product\" } }"
  }'
```

When the request is valid, the response is:

```json
{ "result": { "valid": true } }
```

When the request is invalid, the response includes a list of actionable errors:

```json
{
  "result": {
    "valid": false,
    "errors": [
      {
        "type": "missingBody",
        "message": "This endpoint requires a request body",
        "path": "/{projectKey}/products",
        "suggestion": "Provide a request body for POST /{projectKey}/products. The API defines a schema for this endpoint, indicating a body is expected."
      }
    ]
  }
}
```

**TypeScript example:**

```typescript title="REST validate"
const response = await fetch(
  'https://docs.commercetools.com/apis/rest/tools/rest-validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'POST',
      path: '/my-project/products',
      apiKey: 'api-Product',
      body: JSON.stringify({
        productType: { typeId: 'product-type', key: 'standard-product' },
        name: { en: 'New Product' },
        slug: { en: 'new-product' },
      }),
    }),
  }
);
const data = await response.json();
```

### Privacy policy

Please refer to commercetools [Privacy Notice page](https://commercetools.com/privacy).

### Support

For any issue related to using the MCP server, please report it through the [commercetools support portal](https://support.commercetools.com/).

## Related pages

- [Area overview page with navigation](/dev-tooling.md)
- [Previous page: Self-hosted Commerce MCP](/dev-tooling/mcp/self-hosted-commerce-mcp.md)