Uniple X402 Purchase

This repository contains Uniple's reference Agent Skill, Local MCP server, and the source for the public no-payment Hosted MCP service. The existing Claude Directory endpoint is https://uniple.io/mcp. The separately isolated ChatGPT Apps endpoint is https://uniple.io/mcp/chatgpt.

Skill and MCP servers for agents that discover and quote products exposed by Uniple's x402 catalog API. The repository contains three deliberately separate operating modes:

• Local stdio MCP: catalog, search, shipping quote, and optional local signing.
• Claude Hosted MCP: catalog, search, shipping quote, an unpaid existing LINE/WalletConnect checkout link, and existing-intent status checks.
• ChatGPT Hosted MCP: physical-product catalog/search plus a PII-free link to enter delivery details, review the shipping-inclusive total, and complete or cancel checkout on uniple.io outside ChatGPT.

This is separate from jpyc-ec-purchase. That service uses x402 v2, POST /api/v1/checkout, and PAYMENT-SIGNATURE. Uniple checkout currently uses x402 v1, catalog/payment URLs, and X-PAYMENT.

Cloning this repository is not required to use the Production Hosted MCP. An MCP-capable client can connect to the endpoint intended for its platform; directory discovery inside ChatGPT and Claude remains subject to each platform's separate review and publication process. The endpoints use separate tool contracts and separate Production services. The ChatGPT endpoint exposes only three address-free physical-goods tools. The Claude endpoint keeps its submitted five-tool contract unchanged.

Claude Hosted MCP and Local MCP flow

1. Search every merchant catalog whose AI商品公開 setting is enabled in Uniple admin. Results report whether shipping quotes and Hosted Checkout are currently available; the search can still be limited by merchant ID/domain.
2. After the user explicitly supplies and confirms every required delivery field, send quantity and that confirmed address in a POST JSON body to Uniple and the merchant to obtain a quote. Never infer an address.
3. Validate the quote's product, quantity, subtotal, shipping, discount, total, source, expiry, and atomic x402 amount.
4. When the user asks to continue, create_checkout_link sends the same confirmed delivery fields and accepted total, obtains a fresh quote, and returns the merchant's existing LINE or WalletConnect checkout URL. It refuses a changed total and does not pay.
5. In Local mode only, after explicit purchase approval, sign the server-provided authorizationNonce and repeat the exact same POST body with X-PAYMENT.

The official client does not put shipping PII in the URL and has no shipping GET transport. Its public quote result and MCP tool output do not contain the shipping body; the exact serialized body is kept in-memory by the client only for settlement.

ChatGPT Hosted MCP flow

1. Search all merchants whose AI商品公開 setting is enabled, or browse one merchant explicitly selected by the user. Only physical products are returned.
2. After the user selects one current product and quantity and asks to continue, validate that the SKU is still an available physical product.
3. Return a PII-free /x402/buy?... URL. The MCP request contains only the merchant identifier, SKU, and quantity.
4. The user enters delivery details, obtains and reviews a fresh shipping-inclusive total, and completes or cancels payment on uniple.io outside ChatGPT. The ChatGPT MCP creates no quote, checkout session, payment, or order.

Safety boundary

quote_product never signs or sends funds. Incomplete, expired, product-only, or internally inconsistent quotes are rejected.

Local purchase_product additionally requires:

• BUYER_PRIVATE_KEY in the local process only;
• max_amount_atomic as an explicit budget cap;
• a valid server-provided extra.authorizationNonce and extra.bindingMac (both bytes32);
• explicit user approval before the tool is called.

Never configure a buyer private key on a shared or hosted process.

The Claude Hosted MCP enforces that boundary in code: it exposes only list_products, search_products, quote_product, create_checkout_link, and get_purchase_status, has no signer, and refuses to start if BUYER_PRIVATE_KEY is present. The older PII-free create_purchase_link remains available in Local mode for compatibility but is deliberately not exposed by Hosted MCP because it bypasses the accepted shipping quote and can be confused with the normal checkout handoff.

create_checkout_link is the normal post-quote path. It requires the same user-confirmed delivery fields and exact accepted total, creates only an expiring unpaid CheckoutSession, and returns the existing checkout route: LINE contract merchants use the established LINE identity/setup/payment flow, other merchants use WalletConnect, and both merchants show the established choice screen. Delivery data is never placed in the URL or returned by the tool.

The separate ChatGPT Hosted MCP exposes only list_products, search_products, and create_purchase_link. Its tool schemas accept no name, address, city, phone, email, wallet credential, or payment authorization. The link tool creates no server state and revalidates that the selected SKU is a currently available physical product before returning the PII-free URL.

Local build

git clone https://github.com/uniple/uniple-x402-agent-skill.git
cd uniple-x402-agent-skill
npm ci
npm run typecheck
npm test
npm run build

See LOCAL_MCP_TEST_GUIDE.md for a Windows/WSL verification template.

Local stdio MCP

Catalog, quote, and external purchase-link configuration (no local signing):

{
  "mcpServers": {
    "uniple-x402-purchase": {
      "command": "node",
      "args": [
        "/absolute/path/uniple-x402-agent-skill/mcp-servers/uniple-x402-purchase/dist/bin.js"
      ],
      "env": {
        "UNIPLE_API_URL": "https://approved-compatible-api.example"
      }
    }
  }
}

Replace the reserved example URL with an explicitly approved compatible API base URL. UNIPLE_API_URL is required and has no default; the client will not silently target Production.

Add BUYER_PRIVATE_KEY only to a private local configuration when the user intentionally enables purchase_product. It is not needed for catalog, search, or quote.

Hosted Streamable HTTP MCP (no payment)

The Production endpoints use Streamable HTTP, require no authentication, and expose their platform-specific no-payment tools documented in HOSTED_MCP_PRODUCTION_GUIDE.md. The existing Claude endpoint is https://uniple.io/mcp; the isolated ChatGPT Apps endpoint is https://uniple.io/mcp/chatgpt. The separate development endpoint remains documented in HOSTED_MCP_DEV_GUIDE.md.

npm run build
UNIPLE_API_URL=https://approved-compatible-api.example \
HOSTED_MCP_HOST=127.0.0.1 \
HOSTED_MCP_PORT=3000 \
npm run start:hosted

Endpoints:

• POST /mcp: stateless MCP Streamable HTTP endpoint
• GET /health: reports the active profile and its no-payment tool boundary

The Claude health response reports the existing five tools with purchaseLinkAvailable: false and checkoutLinkAvailable: true. The ChatGPT health response reports its three tools with purchaseLinkAvailable: true and checkoutLinkAvailable: false.

Every Hosted tool declares Apps SDK securitySchemes: [{ "type": "noauth" }] in both the current descriptor field and its _meta compatibility mirror. This metadata describes the implemented no-auth interface. A user can connect the Production URL as a custom connector where supported; directory discovery still requires the separate platform review and publication process.

Put this service behind TLS. It receives delivery details for quotes and for creating an expiring checkout session; do not enable HTTP body/query logging at the proxy. If the reverse proxy preserves an external Host header, configure HOSTED_MCP_ALLOWED_HOSTS as a comma-separated allowlist.

The process rejects MCP JSON bodies over 32 KiB and applies a built-in global and peer rate limit (HOSTED_MCP_RATE_LIMIT_PER_MINUTE, default 120). Edge controls are still required because no-auth clients behind a shared proxy cannot be reliably separated by the application alone.

The Production deployment adds TLS, host validation, request-size controls, application rate limits, and edge controls. Operators of another deployment must provide equivalent protections.

Do not set BUYER_PRIVATE_KEY, even to an empty value. Startup fails whenever that variable exists.

Public policies and support

• Hosted MCP Production guide
• Hosted MCP Privacy Notice
• Support
• Security policy
• Uniple Terms of Service
• Uniple Privacy Policy

Quote contract

quote_product requires a delivery address and accepts no product-only mode. Call it only after the user explicitly supplies and confirms every required shipping field. Never infer or guess delivery data. The confirmed fields are sent to Uniple and the merchant to calculate the quote. The selected catalog product must explicitly declare paymentMethod: "POST" and shippingRequired: true; otherwise the client stops before sending delivery details. The 402 response must include:

• productSku, quantity, and quoteSource
• productSubtotalJpyc, shippingFeeJpyc, discountJpyc, and totalJpyc
• quoteId, expiresAt, shippingDigest, and bytes32 authorizationNonce / bindingMac
• quoteSource matching the SKU platform prefix
• maxAmountRequired exactly equal to totalJpyc in JPYC atomic units

The quote must retain at least 90 seconds of validity. Local purchase signs the exact authorization nonce and caps authorization validity at least 30 seconds before quote expiry. The client does not compare a prior quoteId with a fresh re-quote because the merchant creates a new quote ID for each quote. The required budget cap and fresh, internally consistent quote are used instead.

Catalog price and shipping settings are merchant-controlled and can change. Always display the fresh quote rather than relying on example amounts.

If the paid POST does not return a confirmed paid response—especially 503 payment_recovery_pending—the tool reports paymentStatus: unknown_do_not_repurchase with the response body/transaction hash and deterministic intentId. Call get_purchase_status with that ID. Do not call purchase_product again or create a fresh quote/nonce while the status is pending, manual, not found, or otherwise unresolved. A fresh retry can double-pay.