For Integrators

Developer Documentation

Everything you need to integrate AgenticMCPStores with your application

MCP Agent Setup — 3 steps

Configure your AI agent to browse products, create carts, and initiate checkout through the MCP protocol.

Add the MCP server to your agent

Add AgenticMCPStores to your agent's MCP configuration. Replace {slug} with the merchant store slug.

{
  "mcpServers": {
    "agenticmcpstores": {
      "url": "https://agenticmcpstores.com/{slug}/mcp",
      "headers": { "X-Agent-Api-Key": "agnt_your_key" }
    }
  }
}

No key yet? Try the public demo: https://agenticmcpstores.com/demo-store/mcp (no auth, read-only)

Search products with filters

Call search_products to explore the catalog. Filter by category, price range, or availability.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": { "query": "running shoes", "max_price": 200, "in_stock_only": true, "limit": 5 }
  }
}

Recommended: only proceed to cart if merchant trustScore ≥ 0.70

Create cart and complete checkout

Use create_cart to add items, then preview_checkout to review totals, and complete_checkout to finalize. Always confirm with the user before checkout.

// Step 3a — create cart
{ "method": "tools/call", "params": { "name": "create_cart", "arguments": { "items": [{ "product_id": "prod_abc123", "quantity": 1 }] } } }

// Step 3b — preview checkout
{ "method": "tools/call", "params": { "name": "preview_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

// Step 3c — complete checkout (returns URL, no payment processed)
{ "method": "tools/call", "params": { "name": "complete_checkout", "arguments": { "cart_id": "cart_xyz789" } } }

complete_checkout returns a URL — payment happens on merchant's secure page. Never auto-confirm without user approval.

Quick Start

No API key? Start with the public demo endpoint. Have a key? Jump to the authenticated REST examples below.

No API key — try nowLive

Zero setup — no registration required. Uses MCP protocol (JSON-RPC 2.0). 20 requests/min per IP.

curl https://agenticmcpstores.com/demo-store/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": { "query": "running shoes" }
    }
  }'

Authenticated REST API (requires X-Agent-Api-Key)

curl

curl -X POST https://www.agenticmcpstores.com/api/v1/agent/search \
  -H "X-Agent-Api-Key: agnt_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "running shoes", "limit": 5}'

Python

import requests

response = requests.post(
    "https://www.agenticmcpstores.com/api/v1/agent/search",
    headers={"X-Agent-Api-Key": "agnt_your_key"},
    json={"query": "running shoes", "limit": 5}
)
data = response.json()

JavaScript

const res = await fetch(
  "https://www.agenticmcpstores.com/api/v1/agent/search",
  {
    method: "POST",
    headers: {
      "X-Agent-Api-Key": "agnt_your_key",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query: "running shoes", limit: 5 })
  }
);
const data = await res.json();

Authentication

Two authentication methods depending on your integration type.

Agent API Key (Recommended)

X-Agent-Api-Key: agnt_xxx

For autonomous AI agents. Create a key once — use it without a session.

• agent:read — catalog browsing
• agent:cart — cart creation
• agent:checkout — checkout initiation

JWT Bearer

Authorization: Bearer <token>

For authenticated users. Obtain via POST /api/v1/auth/login.

Create an Agent API Key

# 1. Obtain JWT first
curl -X POST https://www.agenticmcpstores.com/api/v1/auth/login \
  -d '{"email":"you@example.com","password":"..."}' | jq .token

# 2. Create Agent API Key (plaintext returned once — store securely)
curl -X POST https://www.agenticmcpstores.com/api/v1/agent-keys \
  -H "Authorization: Bearer <jwt>" \
  -d '{"scopes":["agent:read","agent:cart","agent:checkout"]}'

Try without a key — Demo & Health endpoints

Live

The demo-store MCP endpoint is public (read-only catalog, JSON-RPC 2.0). The health check is also unauthenticated.

Working cURL — copy and run immediately:

curl https://agenticmcpstores.com/demo-store/mcp \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_products","arguments":{"query":"shoes"}}}'

Demo store MCP endpoint (public, no auth)POST https://agenticmcpstores.com/demo-store/mcp
Health check (GET, no auth)GET https://www.agenticmcpstores.com/api/v1/health

MCP Tools

8 tools available via the MCP endpoint and REST API. All tools require X-Agent-Api-Key authentication. Read-only tools (search, detail, compare, availability) execute without human confirmation — write tools always require it.

Tool	Method	Path	Auth Required	Human Confirmation
`search_products` Search across all merchants	POST	/api/v1/agent/search	Yes	Never
`get_product_detail` Full product data with policies	GET	/api/v1/agent/products/{id}	Yes	Never
`compare_products` Side-by-side product comparison	POST	/api/v1/agent/compare	Yes	Never
`check_availability` Real-time stock and price	GET	/api/v1/agent/availability/{id}	Yes	Never
`create_cart` Cart with stock validation	POST	/api/v1/agent/cart	Yes	Required
`complete_checkout` Returns checkout URL — no payment processing	POST	/api/v1/agent/checkout	Yes	Required
`get_merchant_profile` Trust score, verification level, policies	GET	/api/v1/agent/merchants/{slug}	Yes	Never

Webhooks

Subscribe to events in Settings > Webhooks. All payloads include an X-Webhook-Signature header.

order.createdorder.status_changedcheckout.abandoned

Example payload — order.created

{
  "event": "order.created",
  "timestamp": "2026-03-19T14:32:00Z",
  "orderId": "ord_xyz123",
  "merchantSlug": "running-gear-pro",
  "totalAmount": 124.99,
  "currency": "USD",
  "status": "pending"
}

Verify HMAC-SHA256 signature

Python

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js

import crypto from "crypto";

function verifyWebhook(body: Buffer, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

API Response Format

All agent endpoints return a consistent JSON envelope. Product records are designed to be passed directly to LLM context windows.

{
  "success": true,
  "data": [
    {
      "id": "prod_abc123",
      "name": "Ultra Boost Running Shoe",
      "price": 119.99,
      "currency": "USD",
      "stock_status": "in_stock",
      "merchant": {
        "slug": "running-gear-pro",
        "trust_score": 0.82,
        "verification_level": "STANDARD"
      },
      "policies": {
        "return_window_days": 30,
        "free_shipping_threshold": 75,
        "shipping_estimate_days": "2-4"
      }
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "limit": 5
  }
}

Interactive API Docs

Browse and test all endpoints with Swagger UI. Try requests directly from your browser.

Open Swagger UI

GET /api/docs
HTTP/1.1 200 OK

Swagger UI - Interactive
API Documentation

Developer FAQ

View full FAQ

What authentication method does the AgenticMCPStores API use?

The API uses Bearer token authentication via JWT. Obtain a token by calling POST /api/v1/auth/login, then include it in the Authorization header of subsequent requests.

Is there an MCP endpoint I can connect AI agents to?

Yes. Each store gets a unique MCP endpoint at /mcp/{store-slug}. MCP-compatible AI agents can connect to search products, check availability, and initiate checkout flows.

What rate limits apply to the API?

Free tier: 100 requests/min. Pro tier: 1,000 requests/min. Enterprise: unlimited. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

Which e-commerce platforms are supported natively?

Shopify and WooCommerce are supported natively with automated sync. PrestaShop is supported in beta via the Webservice API. Any other platform can be integrated via our REST API by pushing catalog and order data manually.

How do I get an Agent API key for autonomous AI agents?

Create a key via POST /api/v1/agent-keys with your JWT. The plaintext key is returned once — store it securely. Keys follow the format agnt_xxx and support scopes: search, checkout, and orders.

Does the API return structured product data compatible with LLMs?

Yes. Product responses include normalized fields: name, description, price, currency, stock status, return policy, and shipping estimate — designed to be passed directly to LLM context windows.

How do I handle webhooks for order status updates?

Register a webhook URL in Settings > Webhooks. We POST JSON payloads for events: order.created, order.status_changed, and checkout.abandoned. Verify payloads with the HMAC-SHA256 signature in X-Webhook-Signature.

Is there an OpenAPI / Swagger spec I can import?

Yes. The full OpenAPI 3.0 spec is at /api/openapi.json. Import it into Postman or Insomnia.

Related resources

Protocol Matrix

ACP, AP2, x402, UCP — full comparison

Market Outlook

Agentic commerce data and forecasts

For AI Agents

Trust scores, rate limits, and MCP contracts

Ready to integrate?

Start free today and connect your store to AI agents.

Get Started