Embed Commerce Tools in Your Own MCP Server

The embedded shape is the one the module was designed around. Your MCP server is the product your customers already talk to, and commerce should appear inside it as a few more tools, not as a second server to host and secure. Everything below uses the public package entry points, the same ones the bundled reference server is built from, so the behavior you get embedded is identical to the behavior documented across the rest of this documentation.

npm install mcp-commerce

import {
  createCommerce,
  BundledCatalogSource,
  SqliteCartStore,
} from "mcp-commerce";

const commerce = createCommerce({
  catalogSource: new BundledCatalogSource({ path: "./products.json" }),
  cartStore: new SqliteCartStore({ path: "./carts.sqlite" }),
  config: { currency: "usd", cartTtlSeconds: 3600 },
});

import { registerCommerceTools } from "mcp-commerce";

// yourMcpServer is the McpServer instance you already have
registerCommerceTools(yourMcpServer, commerce);

import {
  createCheckoutService,
  SqliteCheckoutSessionStore,
  StripePaymentProvider,
  NoTaxCalculator,
  WebhookOrderSink,
} from "mcp-commerce";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const checkout = createCheckoutService({
  catalogSource,            // the same source the core uses
  sessionStore: new SqliteCheckoutSessionStore({ path: "./sessions.sqlite" }),
  paymentProvider: new StripePaymentProvider(stripe, {
    successUrl: "https://yourproduct.com/thanks",
    cancelUrl: "https://yourproduct.com/checkout-canceled",
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  }),
  taxCalculator: new NoTaxCalculator(),
  orderSink: new WebhookOrderSink(
    "https://yourproduct.com/hooks/order",
    process.env.ORDER_WEBHOOK_SECRET,
  ),
  config: { sessionTtlSeconds: 3600 },
});

registerCommerceTools(yourMcpServer, commerce, checkout);

import { handleStripeWebhook } from "mcp-commerce";

// inside your HTTP routing, with the raw request body preserved
await handleStripeWebhook(req, res, rawBody, { provider, checkout });

Adding the ACP Endpoints Later

Everything above gives you conversational commerce inside your own tool. When you also want agent platforms to drive your checkout programmatically, the ACP REST surface is one more import on the same checkout service. handleAcpRequest(req, res, rawBody, deps) implements the full /checkout_sessions API, create, retrieve, update, complete, and cancel, with bearer auth, optional HMAC signatures, and idempotency built in. It needs an idempotency store (SQLite or DynamoDB implementations ship in the package) and an auth config holding your bearer token. Because it runs on the same checkout service as the MCP tool, a session created by either surface follows identical pricing and state rules. The wire contract is specified in the ACP endpoints reference.

Design Notes Worth Knowing

A few properties of the embedded integration tend to matter in real deployments. The commerce core is stateless across calls: every operation loads the cart from the store, re-resolves prices from the live catalog, and writes back, so any number of server instances can share a store without coordination. Catalog reads are cached with a TTL you control per source, which keeps a remote or S3 catalog from being fetched on every tool call. All amounts are integer minor units, and totals are always computed server-side, so your tool code never does money math. And the module stores no customer history, completed orders exit through the order sink and expire out of the session store, which keeps the privacy story of your product unchanged. Broader patterns for running commerce operations lean and automated are covered in our ecommerce automation pillar.

For sellers planning what to sell through their tool, pricing digital goods for an agent-driven funnel follows the same fundamentals as any store, our digital product pricing guide is a good companion read.

Testing the Embedded Integration

The package is built to make the commerce path testable inside your own test suite. Construct the core with a BundledCatalogSource pointed at a small fixture catalog and SQLite stores with no path (in-memory), and every test starts from a clean store with zero setup. The MockPaymentProvider is deterministic by design: createPayment returns a predictable mock URL, and completeWithToken responds to the token conventions tok_decline (declined) and tok_3ds (requires authentication), with any other token succeeding. That makes decline handling and 3DS handling ordinary unit tests rather than things you discover in production. The mock also records its calls, so a test can assert that a checkout charged exactly once.

Two integration tests are worth writing before shipping. First, the full happy path: add a product to a cart through the registered tools, run checkout, confirm the session lands in in_progress with a payment URL, then simulate the paid webhook and assert your order sink received one order with the right totals. Second, the price-change race: create a cart, change the fixture catalog price, read the cart again, and assert the totals reflect the new price, that is the anti-tampering recompute working, and it is the behavior your finance team will eventually ask you to prove. The state rules these tests exercise are specified in the security model.