Merchant MCP

Merchant MCP exposes catalog and procurement tools to MCP clients such as Claude, ChatGPT, Postman, or custom agent clients.

For required and optional arguments for every MCP tool, see 05-request-field-requirements.md.

Production MCP endpoint:

https://merchant.thyris.cloud/mcp

Health check:

https://merchant.thyris.cloud/mcp/health

Authentication

Every MCP request must include a developer API key.

Recommended header:

Authorization: Bearer tr_live_your_key_here

Alternative header:

X-Catalog-API-Key: tr_live_your_key_here

For procurement-only clients, this explicit header is also accepted:

X-Procurement-API-Key: tr_live_your_key_here

The same store and merchant scopes described in 03-authentication-and-scopes.md apply to MCP tools.

List Tools

curl -X POST "https://merchant.thyris.cloud/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_live_your_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool Summary

Tool	Purpose
`catalog_list_stores`	List stores visible to the API key.
`catalog_search_products`	Search products.
`catalog_get_product`	Get one product by product UUID, SKU, or external ID.
`catalog_search`	Merchant Commerce search. Every product includes its public merchant profile.
`catalog_get_product_details`	Get complete product details by catalog ID or another supported identifier directly from Merchant Catalog, without executing a Flow.
`catalog_upsert_product`	Create or update a product.
`catalog_delete_product`	Delete a product by product UUID.
`catalog_create_cart`	Create a checkout-ready cart from 10 digit catalog IDs.
`catalog_mutate_cart_items`	Add, update, or remove one or more cart items. Supports bundle payloads.
`catalog_clear_cart`	Clear a cart that does not have a checkout ID.
`catalog_archive_cart`	Archive a cart permanently. Archived carts cannot be reopened.
`catalog_complete_order`	Complete an order from a checkout ID and deduct inventory.
`cart_add_bundle` / `cart_update_bundle` / `cart_remove_bundle`	Merchant Commerce tools for atomic bundle cart mutations.
`refund_create` / `refund_get` / `refund_update`	Request, read, list, and update governed refund records. The payment owner executes the provider refund.
`shipment_create` / `shipment_get` / `shipment_update`	Create, read, list, and update shipment and tracking records.
`procurement_list_stores`	List stores visible to the API key for procurement workflows.
`procurement_list_inventory`	List or search procurement inventory inputs.
`procurement_create_inventory_item`	Create a procurement inventory item. Can include structured auto reorder settings and a free-text `customOrderPolicy`.
`procurement_list_suppliers`	List procurement suppliers.
`procurement_create_supplier`	Create a procurement supplier.
`procurement_list_orders`	List procurement orders.
`procurement_create_order`	Create a procurement order/request. `status=requested` starts the supplier quote request workflow.
`procurement_create_quote_order`	Deprecated. Quotes are created only from supplier email replies.
`procurement_update_order_status`	Update procurement order status except quote states.

Search Products

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "catalog_search_products",
    "arguments": {
      "query": "hoodie",
      "storeId": "STORE_UUID",
      "limit": 5,
      "includeDraft": false
    }
  }
}

Get Product

By product UUID:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "catalog_get_product",
    "arguments": {
      "productId": "PRODUCT_UUID"
    }
  }
}

By SKU:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "catalog_get_product",
    "arguments": {
      "sku": "HOODIE-BLK",
      "storeId": "STORE_UUID"
    }
  }
}

Get Product Details Without A Flow

Prefer the ten-digit catalogId returned by catalog_search:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "catalog_get_product_details",
    "arguments": {
      "catalogId": "1234567890"
    }
  }
}

The tool also accepts productId, sku, or externalId; storeId is recommended for SKU or external-ID lookup. The result is the complete authorized product object with store and public merchant objects. merchant contains id, name, slug, description, logoUrl, websiteUrl, industry, and language; private merchant account and contact fields are not exposed.

For the storefront UI profile, both catalog_search results and catalog_get_product_details results must contain non-empty catalogId, name, price, currency, imageUrl, merchant.name, and merchant.logoUrl. merchant.websiteUrl remains nullable because not every merchant has a public website. Missing UI-required values make the product non-renderable and must be handled during merchant onboarding/catalog synchronization rather than invented by the MCP tool or Flow.

This is a direct read-only MCP tool. The caller does not need to create or execute an ACP Flow.

Upsert Product

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "catalog_upsert_product",
    "arguments": {
      "storeId": "STORE_UUID",
      "sku": "MCP-SKU-001",
      "externalId": "mcp_product_001",
      "name": "MCP Product",
      "description": "Created through Merchant MCP",
      "price": 49.9,
      "currency": "USD",
      "status": "active",
      "inStock": true,
      "inventoryQuantity": 5,
      "imageUrl": "https://example.com/product.jpg",
      "imageUrls": [
        "https://example.com/product.jpg",
        "https://example.com/product-back.jpg"
      ],
      "productUrl": "https://store.example.com/products/mcp-product",
      "otherDetails": {
        "brand": "Acme",
        "category": "Apparel",
        "tags": ["mcp", "demo"]
      }
    }
  }
}

Create Cart

Use catalogId, not product UUID.

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "catalog_create_cart",
    "arguments": {
      "storeId": "STORE_UUID",
      "items": [
        {
          "catalogId": "1234567890",
          "quantity": 2
        }
      ],
      "otherDetails": {
        "channel": "claude"
      }
    }
  }
}

Complete Order

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "catalog_complete_order",
    "arguments": {
      "checkoutId": "chk_1234567890abcdef12345678",
      "payment": {
        "id": "pay_1234567890abcdef12345678",
        "status": "paid",
        "provider": "manual"
      },
      "customer": {
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": "+15551112233"
      },
      "shippingAddress": {
        "line1": "Example Street 1",
        "city": "New York",
        "country": "US",
        "postalCode": "10001"
      }
    }
  }
}

List Procurement Inventory

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "procurement_list_inventory",
    "arguments": {
      "storeId": "STORE_UUID",
      "query": "box",
      "limit": 10
    }
  }
}

Create Procurement Supplier

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "procurement_create_supplier",
    "arguments": {
      "storeId": "STORE_UUID",
      "name": "Acme Components",
      "domain": "supplier.example.com",
      "channel": "api",
      "status": "connected",
      "capabilities": ["inventory_feed", "email_quotes"],
      "contact": {
        "email": "ops@supplier.example.com"
      }
    }
  }
}

Create Procurement Inventory With Custom Policy

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "procurement_create_inventory_item",
    "arguments": {
      "storeId": "STORE_UUID",
      "preferredSupplierId": "SUPPLIER_UUID",
      "name": "Shipping Box 12x10",
      "sku": "BOX-12X10",
      "imageUrls": [
        "https://cdn.example.com/boxes/12x10.png",
        "https://cdn.example.com/boxes/12x10-side.png"
      ],
      "quantityOnHand": 180,
      "reorderPoint": 250,
      "targetStockLevel": 1500,
      "reorderThresholdPercent": 25,
      "maxOrdersPerWeek": 1,
      "autoReorderEnabled": true,
      "customOrderPolicy": "Every Monday morning, if stock is under 800, order enough to reach 1500. Never create a second request while one is still open.",
      "unitCost": 0.42,
      "currency": "USD"
    }
  }
}

Create Procurement Order

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "procurement_create_order",
    "arguments": {
      "storeId": "STORE_UUID",
      "supplierId": "SUPPLIER_UUID",
      "status": "requested",
      "reason": "Request supplier quote for packaging below safety stock.",
      "items": [
        {
          "inventoryItemId": "INVENTORY_ITEM_UUID",
          "name": "Shipping Box 12x10",
          "quantity": 1000,
          "unitCost": 0.42,
          "currency": "USD"
        }
      ]
    }
  }
}

procurement_create_order with status=requested starts the supplier quote request workflow. The supplier quote appears only after a supplier response is received through the supported intake flow.

Outbound Webhook Side Effects

MCP write tools can emit outbound webhook events when a matching destination and event subscription are configured.

MCP Tool	Events	Current `source` Value
`catalog_upsert_product`	`product.created` or `product.updated`	`mcp`
`catalog_delete_product`	`product.deleted`	`mcp`
`catalog_create_cart` / `cart_create`	`cart.created`, and checkout creation when the compatibility cart-create flow prepares checkout immediately	`mcp`
`catalog_mutate_cart_items`, `cart_add_item`, `cart_update_item`, `cart_remove_item`	`cart.item.added`, `cart.item.updated`, `cart.item.removed`, plus `cart.updated`	`mcp`
`cart_add_bundle`, `cart_update_bundle`, `cart_remove_bundle`	`cart.bundle.added`, `cart.bundle.updated`, `cart.bundle.removed`, plus `cart.updated`	`mcp`
`catalog_clear_cart` / `cart_clear`	`cart.cleared`	`mcp`
`catalog_archive_cart` / `cart_archive`	`cart.archived`	`mcp`
`cart_close`	`cart.closed`	`mcp`
`checkout_prepare`	`checkout.created`	`mcp`
`checkout_cancel`	`checkout.cancelled`	`mcp`
`catalog_complete_order`	`order.created`, `order.completed`, `product.inventory.updated`	`mcp`
`refund_create`	`refund.requested`	`mcp`
`refund_update`	Status-specific refund event and `order.refunded` after success	`mcp`
`shipment_create`	`shipment.created` and the initial status event when not pending	`mcp`
`shipment_update`	Status-specific shipment event	`mcp`
`procurement_create_supplier`	`supplier.outbound.created`	`api` because the MCP client currently uses the procurement REST create route
`procurement_create_inventory_item`	`inventory.outbound.created`	`api` because the MCP client currently uses the procurement REST create route
`procurement_create_order`	`procurement.order.created` and workflow events for requested orders	`mcp` by default
`procurement_update_order_status`	Status-specific procurement order event	`api` because the MCP client currently uses the procurement REST update route

The source field describes the engine path that produced the delivery; it does not control whether the event is delivered.

Claude Remote MCP Setup

Open Claude settings.
Go to Connectors.
Add a custom connector.
Name it Thyris Merchant MCP.
Use this server URL:

https://merchant.thyris.cloud/mcp

When prompted for authentication, use the merchant developer API key.
Save and enable the connector in a conversation.

MCP Safety Notes

Use a store-scoped or custom-scoped key when the agent should only operate on specific stores.
Test with read-only workflows first: list stores, search products, get product.
Enable write tools only after confirming the key scope.
Catalog cart/order tools modify business data and inventory.
Procurement supplier, inventory, and order tools modify purchasing data and may trigger supplier communication and webhook workflows.
Quote tools and quote statuses are read-only from MCP. Quotes come from the supported supplier quote intake flow.

Refund and shipment tools

Tool	Purpose	Required arguments
`refund_create`	Request full/partial refund.	`orderId`, `reason`, `idempotencyKey`
`refund_get`	Read one refund or list by order.	Use `refundId` or `orderId` for targeted reads.
`refund_update`	Record payment-owner refund status.	`refundId`, `status`, `idempotencyKey`
`shipment_create`	Create shipment/tracking record.	`orderId`, `idempotencyKey`
`shipment_get`	Read by shipment/tracking reference or list by order.	Use `shipmentId` or `orderId` for targeted reads.
`shipment_update`	Update tracking/status.	`shipmentId`, `status`, `idempotencyKey`

Example MCP call:

{
  "jsonrpc": "2.0",
  "id": "post-purchase-1",
  "method": "tools/call",
  "params": {
    "name": "refund_create",
    "arguments": {
      "orderId": "ord_123",
      "amount": "49.90",
      "currency": "AZN",
      "reason": "customer_return",
      "idempotencyKey": "refund-order-123-attempt-1"
    }
  }
}

ACP direct routed-tool execution uses the same tool arguments inside POST /api/v1/runtime/mcp/tools/execute. For financial/write tools the protected BFF must include the matching session_id and resume_token; missing, expired, wrong-realm, or wrong-session tokens are rejected. Free-text refund creation is approval-gated and may return HTTP 202 with APPROVAL_REQUIRED. Shipment tracking lookup is read-only; shipment creation/status updates remain trusted direct tool/API operations unless an explicitly governed Flow allows them.

Authentication​

List Tools​

Tool Summary​

Search Products​

Get Product​

Get Product Details Without A Flow​

Upsert Product​

Create Cart​

Complete Order​

List Procurement Inventory​

Create Procurement Supplier​

Create Procurement Inventory With Custom Policy​

Create Procurement Order​

Outbound Webhook Side Effects​

Claude Remote MCP Setup​

MCP Safety Notes​

Refund and shipment tools​