VibeCart

VibeCart

Commerce infrastructure for AI-built apps and AI agents.

VibeCart lets a merchant keep their existing app and Stripe account while adding a small, inspectable commerce layer that AI agents can discover and use. Payments settle directly to the merchant's Stripe account; VibeCart does not need to become merchant of record.

The architecture is protocol-first: one trusted commerce backend, then thin MCP/UCP/client adapters around it.

Live production surface

Generic MCP

Endpoint: https://vibecart.vercel.app/mcp

Tools:

• vibecart.list_products
• vibecart.get_product
• vibecart.get_integration_instructions
• vibecart.create_checkout

vibecart.create_checkout supports both the legacy single-product input and a trusted multi-item items[] input. Product prices are resolved on the server; callers do not supply real transaction prices.

Generic MCP clients should use /mcp.

Durable cart

VibeCart's Neon-backed cart is live in production:

• POST /api/cart
• GET /api/cart/:id
• PATCH /api/cart/:id
• DELETE /api/cart/:id
• POST /api/cart/:id/checkout

The cart uses trusted server-side repricing, idempotent creation, optimistic version checks, expiration, multi-item state, and cart-to-Stripe Checkout handoff.

UCP

• Discovery: https://vibecart.vercel.app/.well-known/ucp
• UCP-aware MCP transport: https://vibecart.vercel.app/ucp/mcp
• Released protocol target: UCP 2026-04-08

Production advertises released catalog and cart capabilities. Current cart tools are:

• create_cart
• get_cart
• update_cart
• cancel_cart

UCP calls require meta.ucp-agent.profile and capability negotiation. Do not point an ordinary MCP client at /ucp/mcp.

The order pipeline and released-schema get_order adapter also exist, but get_order remains hidden until its VibeCart Cloud lookup and real merchant permalink dependencies are configured. VibeCart does not advertise optional capabilities before their runtime dependencies are ready.

Stripe checkout and orders

• Trusted multi-line Stripe Checkout creation is supported.
• Stripe webhook signatures are verified before paid events enter the post-payment pipeline.
• Delayed-payment completion is handled separately so orders are not created prematurely.
• Paid Checkout line items are normalized into durable order records when VibeCart Cloud forwarding is configured.
• Trusted merchant product IDs survive Checkout through Stripe Product metadata.

He Said Nothing physical-store pilot

/he-said-nothing is the controlled physical-product pilot for the $39, $59, and $89 mystery gift boxes. The storefront can remain public while ordering fails closed. When the full launch gate is configured it:

• saves the relationship quiz, sizing clues, packaging choice, gift message, and fulfillment note in a durable cart
• opens a cart-bound, idempotent Stripe Checkout Session
• collects email, phone, shipping address, a separately disclosed shipping charge, and optional Stripe automatic tax
• stores the verified paid order, line items, delivery details, gift clues, and event history in Neon
• exposes paid orders only through the HMAC-signed merchant session at /he-said-nothing/admin
• supports the fulfillment states New, Packing, Shipped, Cancelled, and Refunded-in-Stripe

The checkout gate requires every dependency in .env.example; HSN_CHECKOUT_ENABLED=true alone is insufficient. Test and live Stripe keys must match HSN_CHECKOUT_MODE, and live mode additionally requires customer-support, return-policy, and processing-time text.

Merchant catalog source

The built-in lib/products.ts catalog is demo/reference data only. A real merchant can keep SKUs and prices outside VibeCart and point Core at a merchant-controlled HTTPS JSON feed:

VIBECART_CATALOG_URL=https://merchant.example/vibecart/catalog.json
VIBECART_MERCHANT_NAME="Example Merchant"
# Optional when the feed is private:
VIBECART_CATALOG_BEARER_TOKEN=server-side-secret

Accepted response shape:

{
  "products": [
    {
      "id": "sku-123",
      "name": "Example product",
      "description": "Merchant-controlled product data",
      "priceCents": 4900,
      "image": "https://merchant.example/products/sku-123.jpg",
      "variant": "Optional variant"
    }
  ]
}

An array of products at the document root is also accepted. id, name, and a non-negative integer priceCents are required; image URLs, when present, must use HTTPS.

The configured source is shared by generic MCP catalog/checkout, UCP catalog, and durable cart repricing. VibeCart validates the document, rejects duplicate IDs, caps response/product counts, blocks redirects/private-network targets, applies a short timeout, and caches healthy catalog data for 30 seconds. If VIBECART_CATALOG_URL is configured and the source is unhealthy or invalid, commerce operations fail closed; VibeCart does not silently fall back to demo products.

Normal SKU and price changes therefore do not require editing VibeCart TypeScript or redeploying Core.

Agent-client distribution

VibeCart does not build a different commerce engine for every model. OpenAI/Codex/ChatGPT, Claude, Gemini, VS Code, Cursor, and other MCP clients connect to the same backend.

See:

• docs/integrations/agent-clients.md
• integrations/mcp-clients.json
• https://vibecart.vercel.app/mcp-clients.json

Provider adapters are CI-checked to keep Stripe/database/catalog secrets and duplicated commerce logic out of client configuration.

VibeCart Cloud

VibeCart Core is free to self-host. VibeCart Cloud is the optional $29/month managed layer for merchants that want VibeCart to operate the recurring plumbing.

Current Cloud capabilities include:

• durable verified commerce events
• durable normalized paid-order records and order history
• server-to-server order lookup
• signed merchant fulfillment webhooks
• delivery history and bounded retries
• monitoring/alerts and support workflows

Cloud workspace: https://vibecart-cloud-uupzkh.v2.appdeploy.ai/

Merchant checkout revenue still settles directly to the merchant's Stripe account. VibeCart takes no percentage of merchant sales.

Quick start

npm install
npm run dev

Without VIBECART_CATALOG_URL, Core uses the fictional reference catalog for development. Configure a merchant catalog URL before treating products/prices as a real store catalog.

Without a Stripe secret, Checkout runs in clearly labeled demo mode. For live payments, configure STRIPE_SECRET_KEY in the hosting provider's secret/environment settings. Never commit secret values.

Useful public endpoints:

• /start — merchant/client quickstart
• /mcp — generic MCP transport/discovery
• /api/cart — durable cart creation
• /.well-known/ucp — UCP business discovery
• /ucp/mcp — UCP-aware MCP transport
• /mcp-clients.json — machine-readable client compatibility manifest
• /llms.txt — concise machine-readable integration notes
• /agents.md — agent-facing guide
• /api/health — boolean readiness state without secret values
• /cloud — managed Cloud offer

Security model

• Merchant owns the Stripe account and receives merchant funds directly.
• Trusted prices come from the configured server-side merchant catalog provider.
• A configured remote merchant catalog fails closed rather than falling back to demo prices.
• Client-supplied pricing is disabled by default and is prototype-only when explicitly enabled server-side.
• Stripe webhook signatures are verified before post-payment processing.
• Cart state is durable and versioned rather than trusted from the browser/agent.
• Catalog, Stripe, database, and Cloud integration credentials remain server-side.
• Public health/discovery endpoints expose readiness booleans/capabilities, not credential values.
• Optional UCP capabilities are advertised only when their runtime dependencies are valid.

Protocol conformance

CI pins the released UCP v2026-04-08 source and executes VibeCart's real mappers through the official ucp-schema validator. Cart success/error payloads, catalog responses, discovery, and the private order mapper have release-pinned conformance gates.

Current reference limits

• The remote catalog connector is intentionally a simple trusted JSON-provider contract, not yet a multi-merchant catalog control plane with merchant UI, inventory sync, or per-merchant credentials stored by VibeCart Cloud.
• Inventory, automated tax calculation, shipping-rate calculation, returns/refunds, and a complete fulfillment lifecycle are not finished platform services.
• Public UCP order lookup remains activation-gated until its Cloud/permalink runtime dependencies are configured.
• Next.js App Router is the reference implementation; other frameworks should use adapters around the same Core protocol surface rather than fork commerce logic.

North star

VibeCart: commerce infrastructure for every AI agent. Build once. Sell everywhere AI can act.

License

MIT — free to use, modify, distribute, sublicense, and sell under the license terms.