Free ACP Payments Module: Accept Payments in Your MCP Server

What the ACP Payments Module Is

MCP (Model Context Protocol) servers give AI assistants tools: search this catalog, look up that account, generate this asset. What they have not had is a clean way to take money. The moment a company wants to sell a Pro license, a credit pack, or a digital product through its MCP tool, it faces a pile of undifferentiated work: cart state, price math, checkout sessions, payment provider integration, webhook verification, idempotency, and a new protocol (ACP) that agent platforms expect merchants to speak. The ACP Payment Module packages all of that as a drop-in library and reference server, free under the Elastic License 2.0, with the source on GitHub.

The design premise is simple: the commerce should ride along with a product and a brand that already exist. This module is built for companies that already run, or are building, an MCP tool and want to charge for something inside it. The shopper already trusts the brand they are talking to, so the usual cold-start trust problem of an unknown storefront never appears. The module deliberately stays out of the way of your business systems. It is not a CRM, not an order database, and not a customer history store. When a payment succeeds, it hands the completed order to your systems through a signed webhook and keeps nothing, which also keeps your compliance surface small.

Everything ships in one TypeScript package named mcp-commerce that runs on Node.js 20 or newer. The commerce logic is a standalone library, and the two network faces over it are thin: an MCP server exposing shopping tools to agents, and an ACP REST API exposing checkout sessions to agent platforms. The same core also serves an ACP product feed so platforms can discover what you sell, in JSONL or CSV format. You can read the protocol background in What Is the Agentic Commerce Protocol, or jump straight to the quickstart.

Why Agentic Commerce Changes Checkout

Traditional ecommerce assumes a human on a website: they browse pages, click a cart icon, and type card details into a form. Agentic commerce assumes an AI assistant acting for that human. The assistant needs machine-readable products, a checkout API it can drive programmatically, and a payment method it can either hand to the human (a hosted payment link) or execute itself with a scoped, pre-authorized token. The Agentic Commerce Protocol is the emerging standard for that interaction, defining how an agent platform creates a checkout session with a merchant, updates it, and completes payment. OpenAI publishes the specification and Stripe provides the matching payment rails, so merchants who speak ACP can appear as buyable inside AI assistants rather than just linkable.

For a small software company this is a meaningful new sales channel. A developer asking an assistant to upgrade their plan, renew a license, or buy more credits is expressing purchase intent at the exact moment the product is in use. The module makes that moment transactable. The conversation that was already happening becomes the checkout, and the sale completes in seconds instead of bouncing the customer to a website where carts go to be abandoned. Our guides on cart abandonment document how much revenue leaks out of every extra step in a traditional checkout, and agentic checkout removes most of those steps entirely.

The protocol itself is young and still in beta, which is exactly why a maintained open source implementation is useful. The module pins a published ACP spec snapshot (API version 2026-04-17), maps its session states, error codes, and headers faithfully, and isolates all of it behind interfaces, so when the spec moves, the surface that changes is small. The ACP endpoints reference documents the exact wire behavior.

Who This Module Is For

The clearest fit is a software company with an existing MCP tool and something digital to sell inside it. A few concrete shapes show up again and again. SaaS products that expose an MCP server for their users can sell plan upgrades and renewals in the same conversation where the user hits a plan limit. Developer tools can sell licenses and seats: the moment an agent reports that a feature needs Pro, the purchase is one tool call away. API businesses can sell credit packs and top-ups, which suits agents especially well because the buyer is often the same automation that consumes the credits. Asset creators can sell individual digital goods, templates, fonts, models, or stock files, where the agent finds the asset by search and buys it by id.

Teams without an MCP server yet are also served, just through a different door. The standalone server is a complete, runnable store: give it a products file and a Stripe key and you have an MCP endpoint you can register with agent platforms the same day. And teams that want conversational commerce without MCP at all can call the library from whatever stack they already run, since the core never imports a transport. If you are still deciding what to sell, our guide to digital product ideas covers products that fit this kind of instant, no-shipping checkout.

Three Ways to Run It

The module is shaped so that adoption is a gradient, not a cliff. You can run the whole stack, embed the pieces you want, or use the logic as a plain library.

1. Standalone server. Run npm start, the Docker image, or the bundled AWS Lambda handler, and you get a complete commerce server: an MCP endpoint at /mcp, the ACP checkout endpoints under /checkout_sessions, a Stripe webhook receiver at /webhooks/stripe, and the product feed at /feed. This is the fastest path and the right one when your MCP tool does not exist yet or lives elsewhere. The quickstart guide gets this running in a few minutes, and the Lambda deployment guide covers the serverless variant.

2. Embedded in your MCP server. Import the commerce core into the MCP server you already run and call registerCommerceTools(). Your server keeps its transport, its auth, and its existing tools, and gains search_products, add_to_cart, checkout, and the rest alongside them. This is the intended deployment for established tools, covered step by step in embedding commerce tools in your own MCP server.

3. Library only. Skip MCP entirely and call the same functions from a REST API, a Discord bot, or a cron job. createCommerce() and createCheckoutService() return plain objects with promise-returning methods, so anything that runs JavaScript can drive a cart and complete a checkout. Every storage and payment dependency is an interface you can swap, detailed in storage and catalog drivers.

What Happens During a Sale

A typical conversational sale flows through five stages, and seeing them end to end makes the architecture obvious.

Discovery. The agent calls the search_products or get_product tool, which reads your catalog. The catalog is a single JSON file of products, variants, and integer-cent prices that can live on disk, behind a URL, or in S3. The format is documented in the products file reference.

Cart building. The agent calls add_to_cart, receives a cart_id, and passes it back on later calls, because the MCP transport is stateless by design. Quantities change with update_cart_item, lines disappear with remove_from_cart, and view_cart always returns server-computed totals. Prices are re-derived from the live catalog on every operation, so nothing the client sends can alter what gets charged.

Checkout. The checkout tool converts the cart into a checkout session and asks Stripe for a hosted payment URL, which the agent hands to the human. Alternatively, an agent platform drives the ACP REST endpoints directly, creating and updating a session and completing it with a delegated payment token. Both paths share one checkout service and one set of state rules.

Payment. Stripe confirms the charge, either through the shopper finishing the hosted page (a webhook then marks the session paid) or through the immediate token charge on the ACP complete call. Decline and 3DS outcomes map to clean, typed errors. The payment modes guide compares the two paths in depth.

Handoff. The moment a session completes, the module POSTs a signed order payload, line items, buyer, and totals included, to your order webhook, then forgets the order. Your fulfillment, licensing, or CRM systems take over from there, as described in the order webhook guide. If you sell digital goods, our wider guide on digital product delivery pairs well with this step.

Two Payment Modes, One Core

The module supports the two payment shapes that exist in agentic commerce today. Direct payment creates a Stripe Checkout session and returns a hosted URL for the human to open, which works everywhere Stripe works and requires no special program enrollment. Delegated payment accepts a Shared Payment Token (SPT) that an agent platform grants for a specific purchase, and charges it immediately on the ACP complete endpoint, currently a Stripe preview capability for US merchants. The MCP checkout tool uses the direct mode, since an MCP client cannot grant a delegated token, while ACP platform traffic uses the delegated mode. Both are implemented behind one PaymentProvider interface, and a deterministic mock provider stands in whenever no Stripe key is set, so local development never touches real money.

Sales tax follows the same philosophy of delegating to systems that already solved the problem. Tax is off by default, and when you enable it the module uses Stripe Tax to compute line-level tax the moment a buyer address is known, folding it into the session totals. United States sellers dealing with multi-state rules will find the background in our sales tax guide useful, and the module-specific setup lives in sales tax with Stripe Tax.

Price Integrity and Security by Default

Commerce code earns trust through its defaults, and the module ships closed and conservative. The ACP endpoints reject every request until you configure a bearer token. Optional HMAC request signatures fail closed when configured. Every POST requires an idempotency key, scoped to the caller and endpoint, with conflicting reuse rejected and concurrent retries serialized, so a network blip can never double-charge a card. All money is integer minor units end to end, which eliminates the floating point rounding bugs that plague decimal money math. And the anti-tampering rule runs everywhere: unit prices are never read from client input or trusted from storage, they are recomputed from the catalog on every read and mutation, while completed or in-flight sessions are frozen and never re-priced. The full model, including what is logged and what is never stored, is documented in the security model. For broader store hardening practices, see ecommerce security.

Architecture at a Glance

The package is organized as a small core with swappable edges. The core owns products, carts, checkout sessions, totals math, and typed errors. Around it sit five seams, each a TypeScript interface with shipped implementations: catalog sources (bundled file, remote URL, S3), stores for carts, sessions, and idempotency records (SQLite for a single box, DynamoDB for serverless), the payment provider (Stripe, or the mock), the tax calculator (none, fixed rate, or Stripe Tax), and the order sink (signed webhook, or a logging no-op). The MCP tools and the ACP router are both consumers of the same core, which is why behavior never drifts between the conversational path and the platform path. AWS drivers live in a separate mcp-commerce/aws entry point so the AWS SDK never loads unless you use it.

Carts and checkout sessions are the only mutable state, both TTL-expiring and neither containing stored payment details, so the data layer stays disposable. Configuration splits cleanly: non-secret settings live in a config.json file, secrets only ever come from environment variables. The configuration reference lists every key and variable.

Build It Yourself vs Integrate the Module

A capable team can absolutely hand-roll agentic checkout, the building blocks are public: the ACP spec, the Stripe API, and the MCP SDK. What the module saves is the long tail of correctness work that only shows up under real traffic. Idempotent POST handling with body-hash conflict detection, replay headers, and in-flight serialization. Catalog re-resolution on every cart read so a price change mid-session never sells stale prices. Frozen session states so a live hosted payment is never re-priced underneath the shopper. Line-dropping with buyer-visible warnings when a product disappears mid-checkout. Webhook signature verification, late-webhook rules that refuse to resurrect a canceled session, and an order handoff that survives a down merchant endpoint without failing the charge. Each item is a day of thought and a page of tests, and all of them are already written, tested, and documented here.

The integration cost runs the other way and stays small by design. The whole commerce surface is a handful of factory functions and interfaces, the reference server is around four thousand lines of readable TypeScript, and nothing about your existing stack needs to change shape. Teams comparing this decision to the classic platform question, build a store or rent one, will recognize the trade from our ecommerce platform comparisons: own the parts that differentiate you, integrate the parts that do not.

Requirements, License, and Cost

The runtime requirements are deliberately ordinary. Node.js 20 or newer, and a Stripe account when you are ready to take real payments. The package depends on the official MCP SDK, Stripe SDK, zod for validation, and better-sqlite3 for single-box storage. The AWS SDK packages are optional peer dependencies that only install and load if you choose the DynamoDB stores or the S3 catalog source. Docker users get a thin reference image, and serverless users get a ready Lambda handler, so the module runs the same on a laptop, a five dollar VPS, an EC2 box, or Lambda.

The license is Elastic License 2.0. You can use, modify, and embed the module in your own product, including proprietary and commercial ones, at no cost. The single limitation is that you may not resell the module itself as a hosted or managed commerce service to third parties. For the intended audience, a company adding payments to its own MCP tool, that limitation never comes into play. There are no fees, no revenue share, and no hosted dependency on the module's author: your Stripe account, your infrastructure, your customer relationships. The only per-transaction cost in the stack is Stripe's own processing fee, which our payment processing guide breaks down alongside the other major processors.

Getting Started

Technical Reference

Payments and Operations