If you maintain an MCP server, you have probably had someone ask whether they can buy the Pro tier, a credit pack or a license right there in the chat. This post walks through what it takes to add search, cart and checkout tools to a server you already run, without standing up a second service.
Register Commerce as More Tools, Not a New Server
The shape that works is a library you import into your existing server. You create a commerce core from three things: a catalog source, a cart store and a small config object. Then one call, registerCommerceTools(yourMcpServer, commerce), adds search_products, get_product, add_to_cart, view_cart, update_cart_item and remove_from_cart next to the tools you already expose. Your transport, auth and deployment stay exactly as they are.
Checkout is a separate service you pass in as a third argument. It holds the payment provider, a session store, a tax calculator and an order sink, and once it is there the checkout tool appears. During development you can swap in a mock payment provider and a no op order sink, so the whole flow runs with no keys and no charges. The guide to embedding commerce tools in your own MCP server has the full code for each step, including wiring the Stripe webhook so duplicate deliveries are harmless.
Write Tool Descriptions for the Agent That Reads Them
An MCP tool description is the only manual the agent ever reads, so the contract has to live there. The transport is stateless, which means add_to_cart returns a cart_id and the agent must send it back on every later call. Line edits use a line_id, not a product id, and the description says so, because that mix up is the most common agent mistake.
Errors matter as much as success. Returning readable messages with machine codes like missing, invalid and out_of_stock lets an agent recover by searching again, picking a variant or telling the shopper an item is unavailable, instead of stalling. Each result pairs a one line summary for the conversation with a JSON body for the agent's reasoning. The MCP commerce tools reference documents all seven tools with their inputs, outputs and failure cases.
Keep the Catalog and the Cart State Apart
The catalog is read only product truth. It never gets written by commerce code, and it is the only authority on price, kept in integer cents. Every cart read recalculates line prices from the live catalog, so whatever the client sends cannot change what gets charged, and a price change reaches open carts on its own.
The cart is the opposite: per shopper, constantly changing, and worthless after an hour. Modeling carts, checkout sessions and idempotency records as rows that expire means the store cleans itself and holds nothing worth stealing, with no card data and no order archive. SQLite covers a single box, and DynamoDB with conditional writes covers serverless fleets where two containers might handle the same retry. The storage and catalog drivers guide compares the options and the cache settings that bound how stale a price can get.
The Takeaway
Selling inside an MCP server is mostly plumbing you should not have to write twice: a few extra tools with honest descriptions, a catalog that owns every price, and short lived state that expires on its own. Treat commerce as part of the server your users already talk to, and the purchase happens in the same conversation where they asked for it.
Top comments (0)