commercetools Knowledge MCP Server

commercetools Knowledge MCP Server とは？

commercetools Knowledge MCP Server は、開発者向けドキュメントと API 仕様を提供する commercetools 公式の無料 MCP サーバーです。AI エージェントは認証なしで、ドキュメント検索、GraphQL と OpenAPI のスキーマ取得、クエリや REST リクエストの検証を行えます。

commercetools は 2 つの MCP サーバーを提供しています。Commerce MCP は Project 内の Cart や Order などのリソースを操作し、API クライアントの認証情報が必要です。ここで紹介する Knowledge MCP は、公開ドキュメントと API スキーマのコンテンツだけを提供するステートレスなサーバーで、commercetools の Project にアクセスできなくても利用できます。立ち上がりの時間を短縮し、AI コーディングアシスタントがフィールド名を推測せずに正しい commercetools のコードを書けるようにすることを目的としています。

commercetools Knowledge MCP Server の使い方

サーバーは Streamable HTTP でのみ提供されており（ローカルの stdio や SSE はなし）、URL は次のとおりです。

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

API キー、サインイン、Project はいずれも不要です。commercetools はローカルのサーバー名として commercetools-knowledge を推奨しています。

Claude Code

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

Claude Desktop と claude.ai

Customize > Connectors > Add custom connector を開き、名前に commercetools-knowledge、リモート MCP サーバーの URL に https://docs.commercetools.com/apis/mcp を設定します。

Cursor

Cursor Settings > Tools & MCP > New MCP Server で次を追加します。

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

VS Code

ユーザーの mcp.json またはワークスペースの .vscode/mcp.json に追加します。

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

ローカルの stdio サーバーにしか対応していないクライアント向けに、commercetools は mcp-remote でエンドポイントをラップする方法を案内しています。

"commercetools-knowledge": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://docs.commercetools.com/apis/mcp"]
}

JetBrains IDE では、AI Assistant などの MCP 対応プラグインを通じて接続できます。

commercetools Knowledge MCP Server の主な機能

• セマンティックなドキュメント検索：commercetools のドキュメント全体を対象に、コンテンツタイプや製品（Composable Commerce、Frontend、Checkout、Connect、InStore）で絞り込めます。
• リソースごとの GraphQL スキーマ：必要に応じて展開できるスタブ型を含み、エージェントは必要な部分だけを読み込みます。
• リソースごとの OpenAPI 仕様：読み取り、書き込み、統合のバリアントがあり、REST リクエストやクライアントの構築に使えます。
• オフライン検証：Project に触れる前に、GraphQL のクエリ／ミューテーションと REST リクエストを公開されている commercetools スキーマに照らして検証します。
• commercetools-developer-tips プロンプト：key と id の違い、centAmount の最小通貨単位、LocalizedString、クエリ述語、ソート、よくある落とし穴などの規約を読み込みます。
• 無料かつ匿名：認証は不要で、IP アドレスごとに 15 分あたり 100 リクエストに制限されています。

commercetools Knowledge MCP Server のツール

サーバーは 3 つのグループに分かれた 6 つのツールを提供します。

• ドキュメント：commercetools-documentation-search は質問と意味的に近いドキュメントの断片を返します。commercetools-documentation-by-id は、コンテンツ ID（例：ctp:api:type:ProductProjection）がわかっているときにエントリ全体を取得します。
• スキーマ：commercetools-graphql-schemata は Cart などのリソースの部分的な GraphQL スキーマを返し、commercetools-oas-schemata は api-Customer-write などのリソースの自己完結した OpenAPI 仕様を返します。
• 検証：commercetools-graphql-validate はクエリやミューテーションをチェックし、行番号と列番号付きでエラーを返します。commercetools-rest-validate は更新アクションの識別子を含め、メソッド、パス、ボディをチェックします。どちらも読み取り専用で、Project の設定ではなく公開スキーマに対して検証します。

ドキュメントで推奨されている流れは、検索、スキーマ取得、検証、そしてコード生成または呼び出しの実行です。

commercetools Knowledge MCP Server のユースケース

• GraphQL 機能の実装：「初期商品付きのカートを作成するには？ミューテーションを書いて検証して。」
• REST 呼び出しの構築：「顧客情報を更新するエンドポイントを探して、changeEmail 更新アクションを検証して。」
• 概念の確認：「Product と ProductProjection の違いは？」
• プロジェクトの雛形作成：「Checkout をセットアップするには？関係するリソースとそのスキーマを挙げて。」
• 幻覚フィールドの防止：生成したクエリをコードベースに入れる前に、毎回エージェントに検証させます。

commercetools Knowledge MCP Server のトラブルシューティング

• 429 Too Many Requests：IP ごとに 15 分あたり 100 リクエストの制限（Knowledge REST API と共有）に達しています。Retry-After ヘッダーに示された時間だけ待ってください。
• 検索結果が空になる：input をより広く、またはより具体的に言い換え、contentTypes や products の絞り込みを緩めてください。
• リソース名が無効：スペルを確認してください。MCP クライアントはツールのスキーマで使用可能な resourceName の値を確認できます。
• 応答が遅い：サーバーは europe-west1 にあるため、他の地域ではレイテンシが高くなる場合があります。