Obtain an OAuth2 token using the client credentials flow against the commercetools auth server; request the appropriate scopes (view_products, view_orders, manage_my_orders as needed)
Send GraphQL queries to https://api.{region}.commercetools.com/{projectKey}/graphql with Authorization: Bearer <token> and Content-Type: application/json
Use GraphQL field selection to avoid over-fetching: request only the specific product fields (masterVariant, name, slug) needed rather than the full product type with all attributes
Paginate using the GraphQL API's limit and offset arguments on list queries; the total field in the response gives the total count for pagination controls
For complex catalog queries use ProductProjectionSearch via the dedicated /product-projections/search endpoint (REST) rather than the GraphQL list endpoint, as the search endpoint supports full-text, facets, and filters that the GraphQL list does not
Known gotchas
The commercetools GraphQL API does not support all resource types — resources like InventoryEntry, ShoppingList, and some B2B resources may only be available via the REST API; check the API documentation before building a GraphQL-only integration
OAuth2 tokens have a fixed TTL and must be refreshed before expiry; commercetools does not issue refresh tokens for client credentials flow — request a new token using client credentials when the current one expires
GraphQL introspection is available on the commercetools endpoint but may be rate-limited in production; cache the schema locally and use a code generation tool to build typed client code rather than relying on runtime introspection
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp