MCP server
Model Context Protocol server exposing Commerce API operations as tools for AI agents.
The Commerce API exposes a Model Context Protocol (MCP) server at /mcp, allowing AI agents and LLM applications to interact with commerce data through standardized tools.
Free keys reach the 21 storefront tools, with three limits. applyCartCoupon and removeCartCoupon have nothing to act on, because no merchant can create coupons yet. listOrders returns an empty list here: it only lists a signed-in customer's orders, and that needs the REST route. Admin tools need a key with the Admin scope, which starts on Grow. Agent Auth starts on Grow. Paid plans are coming.
Endpoint
POST /mcp
Content-Type: application/json
Authorization: Bearer {jwt} | x-api-key: {key}Uses streamable HTTP transport via mcp-handler.
Available tools
MCP tools mirror the REST API endpoints. Each tool maps to an OpenAPI operationId:
Catalog tools
| Tool | REST equivalent | Description |
|---|---|---|
listProducts | GET /v1/products | Search and list products |
getProduct | GET /v1/products/{id} | Get product by ID |
getProductBySlug | GET /v1/products/by-slug/{slug} | Get product by URL slug |
listCategories | GET /v1/categories | List categories |
getStore | GET /v1/store | Get store info |
listCountries | GET /v1/countries | List countries |
Cart tools
| Tool | REST equivalent | Description |
|---|---|---|
createCart | POST /v1/carts | Create a new cart |
getCart | GET /v1/carts/{id} | Get cart details |
addCartItem | POST /v1/carts/{id}/items | Add item to cart |
updateCartItem | PATCH /v1/carts/{id}/items/{itemId} | Update item quantity |
removeCartItem | DELETE /v1/carts/{id}/items/{itemId} | Remove item |
applyCartCoupon | POST /v1/carts/{id}/coupon | Apply coupon. No merchant can create coupons yet |
removeCartCoupon | DELETE /v1/carts/{id}/coupon | Remove coupon. No merchant can create coupons yet |
setCartShippingAddress | PUT /v1/carts/{id}/shipping-address | Set shipping address |
setCartBillingAddress | PUT /v1/carts/{id}/billing-address | Set billing address |
listCartShippingMethods | GET /v1/carts/{id}/shipping-methods | List shipping options |
listCartPaymentMethods | GET /v1/carts/{id}/payment-methods | List payment options |
setCartShippingMethod | PATCH /v1/carts/{id}/shipping-method | Select shipping method |
placeOrder | POST /v1/carts/{id}/place-order | Place order from cart |
listOrders | GET /v1/orders | List customer orders. Returns an empty list over MCP |
getOrder | GET /v1/orders/{id} | Get order |
Admin tools
| Tool | REST equivalent | Description |
|---|---|---|
adminListProducts | GET /v1/admin/products | List all products |
adminCreateProduct | POST /v1/admin/products | Create product |
adminGetProduct | GET /v1/admin/products/{id} | Get product |
adminUpdateProduct | PATCH /v1/admin/products/{id} | Update product |
adminDeleteProduct | DELETE /v1/admin/products/{id} | Delete product |
adminCreateCategory | POST /v1/admin/categories | Create category |
adminUpdateCategory | PATCH /v1/admin/categories/{id} | Update category |
adminDeleteCategory | DELETE /v1/admin/categories/{id} | Delete category |
adminListOrders | GET /v1/admin/orders | List orders |
adminGetOrder | GET /v1/admin/orders/{id} | Get order detail |
adminCancelOrder | POST /v1/admin/orders/{id}/cancel | Cancel order |
adminGetOrderHistory | GET /v1/admin/orders/{id}/history | Get order history |
adminFulfillOrder | POST /v1/admin/orders/{id}/fulfill | Fulfill order |
adminRefundOrder | POST /v1/admin/orders/{id}/refund | Refund order |
adminListCustomers | GET /v1/admin/customers | List customers |
adminGetCustomer | GET /v1/admin/customers/{id} | Get customer |
adminGetDashboard | GET /v1/admin/dashboard | Dashboard statistics |
adminGetStore | GET /v1/admin/store | Store settings |
adminUpdateStore | PATCH /v1/admin/store | Update store settings |
adminUpdateInventory | POST /v1/admin/inventory | Update inventory |
Authentication
MCP requests use the same authentication as REST:
| Method | Header | Scopes |
|---|---|---|
| Agent JWT | Authorization: Bearer {jwt} | From capability grants |
| API key | x-api-key: {key} | From key metadata |
The MCP handler resolves the caller via resolve-caller.ts and sets context in AsyncLocalStorage for tool execution.
Implementation
Each tool in apps/api/lib/mcp/tools.ts calls the same commerce-service.ts functions as REST route handlers and returns both text content and structuredContent:
server.registerTool('listProducts', { inputSchema: searchProductsQuery.shape }, async (input) => {
const orgId = requireScope('storefront')
const data = await catalog.searchProducts(orgId, searchProductsQuery.parse(input))
return {
content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
structuredContent: data,
}
}Connecting an MCP client
Cursor / Claude Desktop
Add to your MCP config:
{
"mcpServers": {
"prood-commerce": {
"url": "https://api.prood.com/mcp",
"headers": {
"x-api-key": "pkAbC123..."
}
}
}
}Programmatic
Use the @modelcontextprotocol/sdk client:
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport)
const result = await client.callTool({
name: 'listProducts',
arguments: { query: 'shirt', perPage: 5 },
})