Implementing agentic commerce requires defining precise tool schemas, mapping them to your existing ecommerce APIs, handling errors robustly, and testing end-to-end flows. Stores that build stable tool interfaces and validate agent interactions see higher agent-driven conversion rates and fewer failed transactions.
This guide provides concrete implementation patterns, schema examples, error-handling strategies, and testing procedures to make your store reliably accessible to AI shopping agents.
Why Implementation Details Matter
AI agents rely on structured tools and clear contracts. Vague tool definitions, inconsistent error responses, or undocumented rate limits cause agents to retry, fall back to scraping, or drop your store from recommendations. A 2025 survey of 120 AI agent developers found that 72% cited poor API documentation and unstable error responses as top reasons for excluding ecommerce stores from their recommendation sets (source: Agentic API Ecosystem Survey, OpenAgents Community, September 2025).
Stripe launched its official MCP server in early 2026 with OAuth and integrated OpenAI Responses API support, proving that production-grade tool integration is achievable (source: Stripe MCP Documentation, 2026). OpenAI’s Computer-Using Agent (CUA) achieved state-of-the-art results on WebArena and WebVoyager by integrating with real-world checkout flows at DoorDash, Instacart, and Priceline (source: OpenAI Operator Announcement, January 2025). These examples show that success depends on implementation quality, not availability.
Tool Schema Definitions
MCP tools use JSON schemas. Here are three essential tool definitions for ecommerce: product search, product details, and cart creation. These examples follow the MCP specification (version 2025-03-26) (source: Model Context Protocol Specification).
Tool: search_products
{
"name": "search_products",
"description": "Search products by query, category, price range, and availability. Returns sorted results.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Full-text search query."
},
"category": {
"type": "string",
"description": "Product category slug."
},
"price_min": {
"type": "number",
"description": "Minimum price inclusive."
},
"price_max": {
"type": "number",
"description": "Maximum price inclusive."
},
"in_stock_only": {
"type": "boolean",
"default": true,
"description": "Return only in-stock items."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 50,
"description": "Max results to return."
}
},
"required": ["query"]
}
}
Response schema:
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"price": { "type": "number" },
"currency": { "type": "string" },
"in_stock": { "type": "boolean" },
"image": { "type": "string", "format": "uri" },
"url": { "type": "string", "format": "uri" }
}
}
},
"total": { "type": "integer" }
}
}
Tool: get_product_details
{
"name": "get_product_details",
"description": "Return full product information including variants, specs, and ratings.",
"inputSchema": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Product ID or slug."
}
},
"required": ["product_id"]
}
}
Response should include structured fields for agents to parse: name, description, price, currency, availability, brand, gtin, images, variants, aggregateRating, shipping, and returnPolicy.
Tool: create_cart
{
"name": "create_cart",
"description": "Create a new cart with items. Returns a checkout URL.",
"inputSchema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": { "type": "string" },
"quantity": { "type": "integer", "minimum": 1 },
"variant_id": { "type": "string" }
},
"required": ["product_id", "quantity"]
}
}
},
"required": ["items"]
}
}
Response:
{
"type": "object",
"properties": {
"cart_id": { "type": "string" },
"checkout_url": { "type": "string", "format": "uri" },
"total": { "type": "number" },
"currency": { "type": "string" },
"expires_at": { "type": "string", "format": "date-time" }
}
}
Mapping MCP Tools to Ecommerce APIs
Most platforms provide REST or GraphQL APIs. Your MCP server translates tool calls into platform API requests.
Shopify Example: search_products
async function searchProducts(params: any) {
const query = `
query search($query: String!, $first: Int!) {
products(first: $first, query: $query) {
edges {
node {
id
title
handle
priceRange {
minVariantPrice {
amount
currencyCode
}
}
images(first: 1) {
edges {
node {
url
}
}
}
totalInventory
}
}
}
}
`;
const variables = {
query: params.query + (params.category ? ` product_type:${params.category}` : ""),
first: params.limit || 10
};
const response = await fetch(SHOPIFY_STOREFRONT_URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Shopify-Storefront-Access-Token": STOREFRONT_TOKEN
},
body: JSON.stringify({ query, variables })
});
const data = await response.json();
return formatMCPResponse(data.data.products.edges);
}
WooCommerce Example: get_product_details
async function getProductDetails(productId: string) {
const response = await fetch(`${WOOCOMMERCE_API_URL}/products/${productId}`, {
headers: {
"Authorization": `Basic ${Buffer.from(`${CONSUMER_KEY}:${CONSUMER_SECRET}`).toString("base64")}`
}
});
const product = await response.json();
return {
id: product.id.toString(),
name: product.name,
description: product.description,
price: parseFloat(product.price),
currency: "USD", // or from store settings
in_stock: product.stock_status === "instock",
brand: product.attributes.find(a => a.name === "Brand")?.options?.[0],
gtin: product.attributes.find(a => a.name === "GTIN")?.options?.[0],
images: product.images.map(img => img.src),
variants: product.variants?.map(v => ({
id: v.id.toString(),
attributes: v.attributes,
price: parseFloat(v.price),
in_stock: v.stock_status === "instock"
})),
aggregateRating: product.average_rating ? {
ratingValue: parseFloat(product.average_rating),
reviewCount: product.rating_count
} : undefined
};
}
Error Handling and Rate Limiting
Agents need clear, machine-readable errors to retry or hand off to humans. Use HTTP status codes and structured error bodies.
Error Response Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": { "type": "string", "enum": ["INVALID_REQUEST", "NOT_FOUND", "OUT_OF_STOCK", "RATE_LIMITED", "INTERNAL_ERROR"] },
"message": { "type": "string" },
"details": { "type": "object" }
}
}
}
}
Common Error Codes
- INVALID_REQUEST (400): Bad parameters. Example: missing required field, invalid price range.
- NOT_FOUND (404): Product or variant does not exist.
- OUT_OF_STOCK (409): Item cannot be added because inventory is insufficient.
- RATE_LIMITED (429): Too many requests. Include retryAfter.
- INTERNAL_ERROR (500): Server error. Agents may retry after backoff.
Rate Limiting Header
Return rate limit info in headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718697600
Stripe recommends using restricted API keys with per-key rate limits for agent integrations (source: Stripe MCP Best Practices, 2026).
Authentication and Authorization
MCP supports OAuth and bearer tokens. For ecommerce, OAuth with scoped permissions is preferred. Your MCP server should:
- Require a bearer token for all tool calls.
- Validate the token and extract user context.
- Enforce scopes: read:products, write:cart, create:checkout.
Example middleware:
function authenticateRequest(req: any, res: any, next: any) {
const authHeader = req.headers.authorization;
if (!authHeader || !authHeader.startsWith("Bearer ")) {
return res.status(401).json({ error: { code: "UNAUTHORIZED", message: "Missing bearer token" } });
}
const token = authHeader.slice(7);
const user = validateToken(token); // Verify JWT or OAuth token
if (!user) {
return res.status(401).json({ error: { code: "UNAUTHORIZED", message: "Invalid token" } });
}
req.user = user;
next();
}
Testing Agentic Commerce Flows
Unit Tests
Test each tool with valid and invalid inputs. Use a mock ecommerce API.
describe("search_products", () => {
it("returns products matching query", async () => {
const result = await searchProducts({ query: "running shoes", limit: 5 });
expect(result.results).toHaveLength(5);
expect(result.results[0]).toHaveProperty("id");
expect(result.results[0]).toHaveProperty("price");
});
it("returns empty results for no match", async () => {
const result = await searchProducts({ query: "nonexistent product xyz" });
expect(result.results).toEqual([]);
expect(result.total).toBe(0);
});
});
Integration Tests
Run against your staging ecommerce API. Test edge cases: out-of-stock items, invalid variants, rate limits.
curl -X POST https://your-mcp-server.com/tools/search_products \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "running shoes", "limit": 2}'
Verify response matches the MCP schema, includes all required fields, and handles errors correctly.
End-to-End Agent Tests
Use a test agent (Claude Code, ChatGPT dev mode) to simulate real workflows:
- Agent searches for a product.
- Agent retrieves product details.
- Agent adds to cart.
- Agent initiates checkout.
Log each step, measure latency, and confirm the checkout URL works in a browser.
Load Tests
Simulate concurrent agent traffic. Tools like k6 or Artillery work well.
import http from "k6/http";
export let options = {
stages: [
{ duration: "1m", target: 20 },
{ duration: "2m", target: 50 },
{ duration: "1m", target: 0 }
]
};
export default function () {
let payload = JSON.stringify({ query: "shoes", limit: 10 });
let params = { headers: { "Authorization": `Bearer ${__ENV.TOKEN}` } };
http.post("https://your-mcp-server.com/tools/search_products", payload, params);
}
Monitor error rates and response times. If errors exceed 1% during peak load, tune rate limits and add caching.
Monitoring and Observability
Track metrics specific to agent interactions:
- Tool call counts by tool name
- Error rates by error code
- Average latency per tool
- Agent user agents and platforms
- Checkout conversion rate from agent-initiated carts
Use structured logs with correlation IDs to trace agent sessions.
{
"timestamp": "2026-06-18T10:15:22Z",
"correlation_id": "abc-123",
"agent": "chatgpt",
"tool": "create_cart",
"params": { "items": [{ "product_id": "123", "quantity": 1 }] },
"status": "success",
"latency_ms": 145
}
Security Best Practices
- Use OAuth with restricted scopes. Do not expose full admin credentials to agents.
- Validate all input parameters against schemas before processing.
- Sanitize all output to prevent injection attacks.
- Log all agent actions for audit trails.
- Use webhook signatures for payment webhooks (Stripe, PayPal) to verify authenticity.
Common Pitfalls
- Inconsistent field names across tools. Agents rely on stable keys.
- Missing or vague error messages. Agents need actionable errors.
- No rate limits. Agents can overwhelm your API.
- Returning HTML instead of JSON. Agents parse JSON, not HTML.
- Forgetting to include product URLs. Agents need a way to hand off to humans if needed.
Internal Linking
For fundamentals on MCP servers, see What Is an MCP Server and Why Your Ecommerce Store Needs One. To help agents discover your store, set up an llms.txt. Ensure your robots.txt allows AI crawlers by following the robots.txt audit guide.
FAQ
What tool schemas do I need for agentic commerce?
At minimum, define search_products, get_product_details, and create_cart tools. Each tool needs a JSON schema for input parameters and a structured response schema. Include fields like id, name, price, currency, in_stock, image, url, and checkout_url so agents can parse results and hand off to humans.
How do I handle errors for AI agents?
Return HTTP status codes with a JSON body containing error code, message, and optional details. Use standard codes like INVALID_REQUEST (400), NOT_FOUND (404), OUT_OF_STOCK (409), RATE_LIMITED (429), and INTERNAL_ERROR (500). Include a retryAfter header for rate limits so agents know when to retry.
Should I use OAuth or API keys for MCP authentication?
OAuth with scoped permissions is preferred. It lets users authorize agents with specific scopes like read:products or create:checkout and revoke access later. Stripe recommends using restricted API keys with MCP for granular control. Avoid exposing admin keys directly to agents.
How do I test my MCP implementation?
Run unit tests for each tool with valid and invalid inputs. Run integration tests against your staging API. Use test agents like Claude Code or ChatGPT dev mode to simulate end-to-end workflows. Perform load tests to ensure your MCP server handles concurrent agent traffic without exceeding error rate thresholds.
What metrics should I track for agentic commerce?
Track tool call counts by name, error rates by code, average latency per tool, agent platforms and user agents, and checkout conversion rate from agent-initiated carts. Use structured logs with correlation IDs to trace agent sessions. These metrics help identify bottlenecks and improve agent-driven conversion.
Sources
Stripe. “Model Context Protocol (MCP).” Stripe Documentation, 2026. https://docs.stripe.com/mcp
OpenAI. “Introducing Operator.” OpenAI Blog, January 2025. https://openai.com/index/introducing-operator/
Model Context Protocol. “Specification 2025-03-26: Authorization.” https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization
OpenAgents Community. “Agentic API Ecosystem Survey 2025.” September 2025. https://openagents.dev/survey-2025
Ahrefs. “AI Overviews Reduce Clicks Update.” December 2025. https://ahrefs.com/blog/ai-overviews-reduce-clicks-update/
Check your store agent discoverability score free at shopti.ai.