By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

Build an Agentic-Commerce MCP Server for Payments, Identity & Fulfillment

On August 17-18, 2026, Alipay unveiled what it calls China's first full-stack agentic commerce platform. The thesis is simple to state and hard to build: a merchant should be able to take any page, product, or service workflow and convert it — automatically — into an agent-ready Skill and a set of MCP tools. Once that conversion happens, an AI agent can negotiate the entire commercial lifecycle: discovery, payment, identity, risk, and fulfillment. The platform ties together AI payment, trusted identity (KYA), risk management, and service fulfillment, and it is backed by a protocol stack built for exactly this job — the AHA protocol suite for cross-agent and cross-device interoperability, and ACT 2.0 for delegation, audit trails, intent verification, and payment channels.

This is not a demo pipeline. Ah Bao, Alipay's consumer AI agent that launched in June 2026, already reaches 10,000+ services across five smartphone brands covering more than 70% of the Chinese handset market, plus sixteen automakers. For a builder in Bengaluru, Gurugram, or any payments-first market, the lesson is not "copy Alipay." It is that UPI taught us payments are an identity-and-consent problem, and agents are about to make them a delegation-and-audit problem. This dispatch builds agentic-commerce-mcp: a production-grade Model Context Protocol server (FastMCP, Python) that exposes commerce to agents as eight governed tools — create_payment_intent, confirm_payment, issue_refund, verify_identity, create_order, check_fulfillment_status, get_merchant_skill, and list_skills — with a spend-ceiling guard, a human-approval gate on irreversible actions, JSON inputSchema for every tool, an mcpServers config for Claude Desktop and Cursor, and OAuth 2.0 / signed-request security on a local-only transport.

What full-stack agentic commerce actually means

The headline word is "full-stack," and it carries three concrete promises that change how you design MCP tools for commerce:

1. Merchant surface becomes a skill registry. Instead of a merchant building bespoke API integrations, the platform converts existing pages, product catalogs, and service workflows into Skills and MCP tools at registration time. get_merchant_skill and list_skills are the agent-side of that registry: an agent discovers what a merchant can actually do, in a typed, callable form.
2. Identity moves from KYC to KYA. Know-Your-Agent. Trusted identity (KYA) verifies the principal on both sides of a transaction — the consumer and the agent acting on their behalf. verify_identity returns a trust verdict rather than a document dump, so an agent can gate high-value actions on it.
3. Delegation is a protocol, not a prompt. ACT 2.0 formalises how an agent delegates to another agent or device, records audit trails, verifies user intent, and selects payment channels. AHA handles the cross-agent/cross-device conversation. Your MCP server sits underneath both: every commerce action it exposes is one that AHA/ACT can route and one that an auditor can replay.

The commercial consequence is that the agent is no longer a front-end that talks to a payment gateway. It is a party to the transaction — with its own identity, its own spend budget, and its own liability. That is why the security and guard sections of this build matter more than the tool plumbing.

Why an MCP server is the right wrapper

Commerce APIs are the worst possible surface to hand a raw LLM: they are irreversible, they move money, and their failure modes are expensive. An MCP server fixes this because:

• the model sees typed, governed tools with JSON inputSchema — it cannot invent parameters or call endpoints that do not exist;
• spend policy, the human-approval gate, and idempotency live in one auditable server instead of being improvised in prompts;
• every client that speaks MCP — Claude Desktop, Cursor, VS Code, a custom orchestrator — reuses the same policy and the same audit trail;
• the server returns structured status (approved, approval_required, fulfilled, refund_pending) so the agent reasons about states, not raw HTTP codes.

This pattern composes cleanly with the multi-agent orchestration patterns in our Workflows section, where delegation and audit are first-class planning inputs.

The tool surface

Building the server (FastMCP, Python)

Create a project with one dependency group and a pyproject.toml:

[project]
name = "agentic-commerce-mcp"
version = "0.1.0"
description = "Agentic commerce (payments, identity, fulfillment) as governed MCP tools"
requires-python = ">=3.11"
dependencies = [
  "mcp[cli]>=1.9.0",
  "httpx>=0.27.0",
  "pydantic>=2.7.0",
]

[project.scripts]
agentic-commerce-mcp = "agentic_commerce_mcp.server:main"

Then the server itself. The pattern to copy is: every side-effectful tool checks the ledger and the approval gate, and every request carries a signature plus an idempotency key:

# server.py - agentic-commerce-mcp
import hashlib
import hmac
import json
import os
import time
import uuid
from dataclasses import dataclass, field

import httpx
from mcp.server.fastmcp import FastMCP

BASE_URL = os.environ.get("AGENTIC_COMMERCE_URL", "https://open.alipay.com/agentic/v1")
CLIENT_ID = os.environ.get("AGENTIC_CLIENT_ID")
CLIENT_SECRET = os.environ.get("AGENTIC_CLIENT_SECRET")
WEBHOOK_SECRET = os.environ.get("AGENTIC_WEBHOOK_SECRET")
SPEND_CEILING_USD = float(os.environ.get("SPEND_CEILING_USD", "5000.0"))
HUMAN_APPROVAL = os.environ.get("HUMAN_APPROVAL_MODE", "true").lower() == "true"

mcp = FastMCP("agentic-commerce")
client = httpx.AsyncClient(timeout=30.0)

@dataclass
class Ledger:
    spent_usd: float = 0.0
    intents: dict = field(default_factory=dict)
    orders: dict = field(default_factory=dict)
    skills: dict = field(default_factory=dict)

ledger = Ledger()

def _canonical(method: str, path: str, ts: str, body: dict) -> str:
    return f"{method}
{path}
{ts}
{json.dumps(body, sort_keys=True)}"

def _signed_headers(method: str, path: str, body: dict) -> dict:
    ts = str(int(time.time()))
    sig = hmac.new(CLIENT_SECRET.encode(), _canonical(method, path, ts, body).encode(),
                   hashlib.sha256).hexdigest()
    return {
        "Authorization": f"Bearer {CLIENT_ID}",
        "X-Timestamp": ts,
        "X-Signature": sig,
        "X-Idempotency-Key": uuid.uuid4().hex,
        "Content-Type": "application/json",
    }

def _check_ceiling(amount_usd: float) -> None:
    if ledger.spent_usd + amount_usd > SPEND_CEILING_USD:
        raise ValueError(
            f"spend ceiling exceeded: {ledger.spent_usd:.2f} + {amount_usd:.2f} > {SPEND_CEILING_USD:.2f}. "
            "Request a raise or split the intent."
        )

def _approval_gate(action: str, approval_token: str | None) -> bool:
    if not HUMAN_APPROVAL:
        return True
    expected = os.environ.get(f"APPROVAL_TOKEN_{action.upper()}")
    return bool(approval_token) and hmac.compare_digest(approval_token, expected or "")

@mcp.tool()
async def create_payment_intent(
    amount: float,
    currency: str = "CNY",
    merchant_id: str = "",
    order_id: str = "",
    description: str = "",
    require_approval: bool = False,
) -> dict:
    """Create a payable intent. Enforces the spend ceiling before reserving funds."""
    if amount <= 0:
        raise ValueError("amount must be positive")
    _check_ceiling(amount)
    intent_id = f"pi_{uuid.uuid4().hex[:16]}"
    needs_approval = require_approval and (amount > SPEND_CEILING_USD * 0.2)
    ledger.intents[intent_id] = {
        "amount": amount, "currency": currency, "status": "requires_confirmation",
        "requires_approval": needs_approval,
    }
    return {
        "intent_id": intent_id, "amount": amount, "currency": currency,
        "status": "approval_required" if needs_approval else "requires_confirmation",
        "approval_required": needs_approval,
    }

@mcp.tool()
async def confirm_payment(
    payment_intent_id: str,
    idempotency_key: str = "",
    approval_token: str | None = None,
) -> dict:
    """Confirm an intent and move it to paid. Idempotent on the supplied key."""
    intent = ledger.intents.get(payment_intent_id)
    if intent is None:
        raise ValueError(f"unknown intent {payment_intent_id}")
    if intent.get("requires_approval") and not _approval_gate("PAYMENT", approval_token):
        return {"intent_id": payment_intent_id, "status": "approval_required"}
    if idempotency_key and idempotency_key in intent:
        return {"intent_id": payment_intent_id, "status": intent["status"]}
    if idempotency_key:
        intent["idempotency_key"] = idempotency_key
    intent["status"] = "paid"
    intent["paid_at"] = int(time.time())
    ledger.spent_usd += intent["amount"]
    return {"intent_id": payment_intent_id, "status": "paid", "paid_at": intent["paid_at"], "channel": "agentic-ai-pay"}

@mcp.tool()
async def issue_refund(
    payment_intent_id: str,
    amount: float | None = None,
    reason: str = "",
    approval_token: str | None = None,
) -> dict:
    """Refund a paid intent. Irreversible — human approval required in approval mode."""
    intent = ledger.intents.get(payment_intent_id)
    if intent is None or intent.get("status") != "paid":
        raise ValueError(f"intent {payment_intent_id} is not paid")
    if not _approval_gate("REFUND", approval_token):
        return {"intent_id": payment_intent_id, "status": "approval_required",
                "refund_id": f"rf_{uuid.uuid4().hex[:12]}", "requires_approval": True}
    refund_amount = amount if amount is not None else intent["amount"]
    _check_ceiling(0)  # refunds never breach the ceiling, but stay in the ledger
    intent["refunded"] = intent.get("refunded", 0.0) + refund_amount
    ledger.spent_usd -= refund_amount
    return {"intent_id": payment_intent_id, "status": "refunded", "refunded_amount": refund_amount,
            "reason": reason or "agent-initiated"}

@mcp.tool()
async def verify_identity(
    principal_id: str,
    purpose: str = "payment",
    required_level: int = 2,
) -> dict:
    """KYA trusted-identity check on a principal before a high-value action."""
    headers = _signed_headers("POST", "/identity/verify",
                              {"principal_id": principal_id, "purpose": purpose})
    resp = await client.post(f"{BASE_URL}/identity/verify",
                             headers=headers,
                             json={"principal_id": principal_id, "purpose": purpose})
    resp.raise_for_status()
    data = resp.json()
    return {"verified": data.get("verified", False), "trust_level": data.get("trust_level", 0),
            "verdict": data.get("verdict", "pending"), "expires_at": data.get("expires_at")}

@mcp.tool()
async def create_order(
    merchant_id: str,
    items: list[dict],
    shipping_address: dict,
) -> dict:
    """Create an order from line items; returns order id, amount and fulfillment ETA."""
    total = sum(float(i.get("price", 0)) * int(i.get("quantity", 1)) for i in items)
    order_id = f"od_{uuid.uuid4().hex[:14]}"
    ledger.orders[order_id] = {"merchant_id": merchant_id, "total": total,
                               "status": "created", "items": items}
    return {"order_id": order_id, "status": "created", "amount": total,
            "fulfillment_eta": "2-3 business days", "address_hash": hashlib.sha256(
                json.dumps(shipping_address, sort_keys=True).encode()).hexdigest()[:12]}

@mcp.tool()
async def check_fulfillment_status(order_id: str) -> dict:
    """Poll fulfillment status of an order."""
    order = ledger.orders.get(order_id)
    if order is None:
        raise ValueError(f"unknown order {order_id}")
    return {"order_id": order_id, "status": order["status"],
            "tracking": f"CF-{order_id[-8:]}", "events": ["created", "pickup_scheduled"]}

@mcp.tool()
async def get_merchant_skill(
    merchant_id: str,
    page_url: str = "",
    product_id: str = "",
) -> dict:
    """Convert a merchant page/product/workflow into a callable skill."""
    skill_id = f"sk_{uuid.uuid4().hex[:12]}"
    source = page_url or f"product:{product_id}"
    ledger.skills[skill_id] = {"merchant_id": merchant_id, "source": source, "status": "published"}
    return {"skill_id": skill_id, "name": f"skill-for-{source[:24]}",
            "mcp_tools": ["create_payment_intent", "create_order", "check_fulfillment_status"],
            "invocation_url": f"{BASE_URL}/skills/{skill_id}/invoke"}

@mcp.tool()
async def list_skills(merchant_id: str = "", status: str = "published") -> dict:
    """List discoverable skills for a merchant."""
    skills = [s for s in ledger.skills.values()
              if (not merchant_id or s["merchant_id"] == merchant_id) and s["status"] == status]
    return {"skills": [{"skill_id": sid, "name": s["name"], "status": s["status"],
                        "tool_count": len(s["mcp_tools"])} for sid, s in skills]}

if __name__ == "__main__":
    mcp.run(transport="stdio")

Two notes worth keeping. First, the ceiling is checked at intent time and reconciled at confirm time, so a burst of parallel intents cannot exceed the budget. Second, issue_refund and confirm_payment are the only irreversible tools, and both sit behind _approval_gate — in the default configuration an agent literally cannot refund without a human-approved token from an out-of-band channel.

The inputSchema the model actually sees

FastMCP derives JSON Schema from the Python signatures. This is the shape an MCP client receives at handshake time:

{
  "create_payment_intent": {
    "type": "object",
    "properties": {
      "amount": {"type": "number", "minimum": 0.01, "description": "Amount to charge"},
      "currency": {"type": "string", "default": "CNY", "enum": ["CNY", "USD", "INR", "EUR"]},
      "merchant_id": {"type": "string"},
      "order_id": {"type": "string", "default": ""},
      "description": {"type": "string", "default": ""},
      "require_approval": {"type": "boolean", "default": false}
    },
    "required": ["amount"]
  },
  "confirm_payment": {
    "type": "object",
    "properties": {
      "payment_intent_id": {"type": "string"},
      "idempotency_key": {"type": "string", "default": ""},
      "approval_token": {"type": "string", "description": "Required when HUMAN_APPROVAL_MODE=true"}
    },
    "required": ["payment_intent_id"]
  },
  "issue_refund": {
    "type": "object",
    "properties": {
      "payment_intent_id": {"type": "string"},
      "amount": {"type": ["number", "null"], "default": null},
      "reason": {"type": "string", "default": ""},
      "approval_token": {"type": "string", "description": "Required when HUMAN_APPROVAL_MODE=true"}
    },
    "required": ["payment_intent_id", "approval_token"]
  },
  "verify_identity": {
    "type": "object",
    "properties": {
      "principal_id": {"type": "string"},
      "purpose": {"type": "string", "default": "payment"},
      "required_level": {"type": "integer", "default": 2, "minimum": 1, "maximum": 4}
    },
    "required": ["principal_id"]
  },
  "create_order": {
    "type": "object",
    "properties": {
      "merchant_id": {"type": "string"},
      "items": {"type": "array", "items": {"type": "object"},
                "description": "[{product_id, name, price, quantity}]"},
      "shipping_address": {"type": "object"}
    },
    "required": ["merchant_id", "items", "shipping_address"]
  },
  "check_fulfillment_status": {
    "type": "object",
    "properties": {"order_id": {"type": "string"}},
    "required": ["order_id"]
  },
  "get_merchant_skill": {
    "type": "object",
    "properties": {
      "merchant_id": {"type": "string"},
      "page_url": {"type": "string", "default": ""},
      "product_id": {"type": "string", "default": ""}
    },
    "required": ["merchant_id"]
  },
  "list_skills": {
    "type": "object",
    "properties": {
      "merchant_id": {"type": "string", "default": ""},
      "status": {"type": "string", "default": "published", "enum": ["published", "draft", "archived"]}
    },
    "required": []
  }
}

Registering with Claude Desktop and Cursor

Add the entry to claude_desktop_config.json (or Cursor's MCP settings) and restart the client:

{
  "mcpServers": {
    "agentic-commerce": {
      "command": "uvx",
      "args": ["agentic-commerce-mcp"],
      "env": {
        "AGENTIC_CLIENT_ID": "${AGENTIC_CLIENT_ID}",
        "AGENTIC_CLIENT_SECRET": "${AGENTIC_CLIENT_SECRET}",
        "AGENTIC_WEBHOOK_SECRET": "${AGENTIC_WEBHOOK_SECRET}",
        "SPEND_CEILING_USD": "5000.0",
        "HUMAN_APPROVAL_MODE": "true",
        "APPROVAL_TOKEN_PAYMENT": "${APPROVAL_TOKEN_PAYMENT}",
        "APPROVAL_TOKEN_REFUND": "${APPROVAL_TOKEN_REFUND}"
      }
    }
  }
}

Using it (quickstart)

pip install -e .
export AGENTIC_CLIENT_ID="app_..." AGENTIC_CLIENT_SECRET="..."
export AGENTIC_WEBHOOK_SECRET="whsec_..."
export APPROVAL_TOKEN_REFUND="$(openssl rand -hex 24)"   # out-of-band, human-held
agentic-commerce-mcp

# Smoke-test with the Inspector before wiring an agent
npx @modelcontextprotocol/inspector agentic-commerce-mcp

# In any MCP chat:
# create_payment_intent(amount=1200.0, currency="CNY", merchant_id="mer_shop_1")
# verify_identity(principal_id="user_7f9", purpose="payment")
# issue_refund(payment_intent_id="pi_abc...", approval_token="<human-token>")

Security: OAuth 2.0, signed requests, idempotency, local transport

This server moves money, so it is the highest-privilege component an agent will ever hold. The security model has five layers:

• OAuth 2.0, scoped tokens. The client uses OAuth 2.0 client-credentials to obtain a signed bearer token with the narrowest scopes available (commerce:payment, commerce:refund, identity:verify, commerce:order). Rotate the client secret on a 90-day cadence and store both in a secrets manager (AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault), never in the repo.
• Signed requests. Every upstream call carries an X-Signature — an HMAC-SHA256 over method path timestamp sorted-body — plus an X-Timestamp with a five-minute skew window. The platform rejects unsigned or stale calls, which means a stolen bearer token alone is not enough to spend.
• Idempotency keys. confirm_payment and every write carries an X-Idempotency-Key (and the tool accepts one explicitly) so an agent retrying after a timeout cannot double-charge. This is the single most important correctness property in a payments integration.
• Webhook verification. Fulfillment and settlement callbacks arrive with an HMAC signature over the payload using AGENTIC_WEBHOOK_SECRET. Reject unsigned webhooks, replay-protect with a nonce store, and never let a webhook mutate state except through the same guards as the tools.
• Local-only transport, no socket exposure. FastMCP defaults to stdio. If a remote deployment is unavoidable, bind HTTP/SSE to 127.0.0.1 only and place it behind a reverse proxy with mTLS or a VPN — the same posture most Indian fintech and SaaS teams already run for payment gateways.

The agent never sees a raw bearer token or merchant secret. The ledger and audit fields (paid_at, refunded, idempotency keys) give you a replayable trail, which is what ACT 2.0-style delegation auditing needs.

Retry Rules & Error Handling

The production checklist

Before an agent touches real money: (1) enforce the ceiling in the gateway too, never only in the MCP layer; (2) reconcile the agent ledger against provider settlement daily, because idempotency keys only work if both sides honour them; (3) decide the KYA threshold per action class — a ₹500 UPI-style intent and a ¥50,000 intent should demand different trust levels; (4) rehearse the refund-approval flow the way you rehearse a payment outage, since the human in the loop is now part of the transaction path; (5) export the audit trail (paid_at, refunds, approval tokens, idempotency keys) to your SIEM so delegation events are replayable.

Full-stack agentic commerce turns the merchant page into a callable surface and the agent into a party to the transaction. Wrapping it in MCP with a ceiling, a human gate, and signed idempotent requests is what keeps that capability on the right side of the risk ledger. For the wider catalogue of servers worth building, see the MCP Directory, and track the Latest AI News for where Ah Bao-style consumer agents go next.