How to Build an MCP Server for Ecommerce: The Developer Guide

Last updated: March 2026

Every AI shopping experience shipping today runs on the same plumbing. When ChatGPT recommends a product and lets you buy it in-chat, when Google AI Mode surfaces merchant inventory, when a LangChain agent builds a cart across three stores – the transport layer underneath is MCP. The Model Context Protocol has become the universal connector between AI agents and commerce systems, and building an MCP server is now the single highest-leverage investment a commerce developer can make.

This guide covers the protocol itself, the reference implementations already in production, the architecture patterns that work, and how to get your first commerce MCP server running.

---

What Is MCP?

The Model Context Protocol is an open standard (Apache 2.0) originally developed by Anthropic in late 2024. It defines a JSON-RPC 2.0 interface for connecting AI agents to external tools and data sources. Think of it as a USB-C port for AI: a universal connector that any agent can plug into, regardless of the model or framework behind it.

An MCP server exposes tools (functions an agent can call), resources (data an agent can read), and prompts (templates for structured interactions). In commerce, this translates to tools like search_catalog, create_cart, apply_discount, and complete_checkout.

The protocol supports two transport mechanisms:

• stdio – local process communication, used for development and CLI-based agents
• HTTP SSE (Server-Sent Events) – remote communication over HTTP, used for production deployments

Every MCP interaction follows the same pattern: the client sends a JSON-RPC request specifying a tool name and arguments, and the server returns structured data. No proprietary SDK lock-in, no framework dependency.

---

Why MCP for Commerce

MCP is the common transport layer across every major commerce protocol and platform shipping today. Google’s Universal Commerce Protocol (UCP) uses MCP as one of its three first-class transports. OpenAI and Stripe’s Agentic Commerce Protocol (ACP) can be implemented as an MCP server. Shopify, PayPal, Stripe, commercetools, and Salesforce Commerce Cloud all ship MCP servers.

This convergence means a single MCP server implementation makes your commerce system accessible to Claude, ChatGPT, Gemini, Copilot, Perplexity, and every agent framework (LangChain, CrewAI, Vercel AI SDK, Google ADK, OpenAI Agents SDK) without building separate integrations for each.

The alternative – building bespoke REST integrations for each AI platform – scales linearly with the number of platforms. MCP scales once.

---

Reference Implementations in Production

Shopify: Three MCP Servers

Shopify ships three production MCP servers, each serving a different scope.

Storefront MCP Server (per-store, no auth required)

Endpoint: https://{shop}.myshopify.com/api/mcp

Every Shopify store has this endpoint active by default. It exposes four tools:

Tool	Purpose
search_shop_catalog	Search a single store’s products by query and buyer context
search_shop_policies_and_faqs	Retrieve store policies, shipping info, returns
get_cart	Get cart contents and checkout URL
update_cart	Add, remove, or update cart items; creates a new cart if no ID provided

No API key needed. You can call it right now:

const response = await fetch('https://yourstore.myshopify.com/api/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    id: 1,
    params: {
      name: 'search_shop_catalog',
      arguments: {
        query: 'organic cotton t-shirt',
        context: 'buyer prefers sustainable brands, budget under $40'
      }
    }
  })
});

Responses include product name, price, currency, variant ID, product URL, image URL, and description. Cart responses include a checkout URL that redirects to Shopify’s hosted checkout.

Catalog MCP Server (cross-merchant, OAuth required)

Endpoint: https://discover.shopifyapps.com/global/mcp

This server searches products across every Shopify merchant. It requires OAuth2 client credentials (JWT with 60-minute TTL) obtained from the Shopify Dev Dashboard.

Tools: search_global_products and get_global_product_details. The search tool accepts filters for price range, shipping origin/destination, availability, subscription products, and specific shop IDs. Results return up to 300 items per query with ratings, top features, tech specs, and unique selling points.

Checkout MCP Server (UCP-compliant, JWT auth)

Endpoint: https://{shop-domain}/api/ucp/mcp

This server implements the full checkout lifecycle: create_checkout, get_checkout, update_checkout, complete_checkout, and cancel_checkout. Authentication uses JWT tokens from POST https://api.shopify.com/auth/access_token with a 24-hour TTL. All amounts are in minor currency units (cents). The complete_checkout and cancel_checkout tools require idempotency keys.

Dev MCP Server (developer tooling)

Package: @shopify/dev-mcp@latest

This is not customer-facing. It provides development tools (learn_shopify_api, introspect_graphql_schema, validate_graphql_codeblocks, validate_theme) for building Shopify apps with AI assistants like Claude Code or Cursor.

Setup: claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

PayPal Agent Toolkit

Portal: mcp.paypal.com GitHub: github.com/paypal/agent-toolkit Package: npm install @paypal/agent-toolkit

PayPal’s toolkit exposes 30+ tools spanning invoices, orders, payments, refunds, disputes, shipment tracking, catalog management, subscriptions, and transaction reporting. It works as both a local MCP server (for Claude Desktop, Cursor) and a remote MCP server with PayPal OAuth.

import { PayPalAgentToolkit } from '@paypal/agent-toolkit';

const toolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    context: { sandbox: true },
    actions: {
      orders: { create: true, capture: true },
      invoices: { create: true, send: true },
      subscriptions: { create: true, list: true }
    }
  }
});

// Works with Vercel AI SDK, LangChain, OpenAI Agent SDK, or raw MCP
const tools = toolkit.getTools();

Salesforce Commerce Cloud MCP

Status: Pilot Protocol: HTTP SSE + JSON-RPC 2.0 Authentication: SLAS JWT tokens with scope sfcc.shopper-mcpagent

Endpoints follow the pattern:

SSE:  https://{short-code}.api.commerce.salesforce.com/mcp/shopper/v1/organizations/{org_id}/sse
Messages: https://{short-code}.api.commerce.salesforce.com/mcp/shopper/v1/organizations/{org_id}/mcp/messages?sessionId={id}

Tools: search_product, get_product, create_basket, add_product_to_basket, get_basket, remove_basket, checkout (generates a PWA Kit storefront checkout link).

commercetools Commerce MCP

Status: GA Framework support: OpenAI Agent SDK, Vercel AI SDK, LangChain, CrewAI

Covers the full commerce lifecycle: product catalog search, cart management (create, add items, apply discounts, check inventory, place orders), order lookups, returns processing, customer data access, and pricing/promotions. Built-in governance and access controls enforce security boundaries.

Stripe MCP Server

Run with: npx -y @stripe/mcp --api-key=YOUR_KEY Docs: docs.stripe.com/mcp

Exposes Stripe API operations and knowledge base search as MCP tools. Works with test API keys for sandbox development. Part of Stripe’s broader agentic commerce suite, which includes @stripe/agent-toolkit for function-calling integration and the hosted ACP endpoint.

---

Architecture Patterns for Commerce MCP Servers

Commerce MCP servers follow consistent structural patterns regardless of the platform.

Pattern 1: Stateless catalog server. No auth, no session state. Accepts search queries, returns product data. Shopify’s Storefront MCP is the canonical example. Best for product discovery agents and prototyping.

Pattern 2: Session-based checkout server. JWT-authenticated, maintains checkout session state. Accepts line items, buyer info, fulfillment preferences, and payment tokens. Returns session status, totals, and fulfillment options. Shopify’s Checkout MCP and any ACP implementation follow this pattern. The checkout state machine progresses through defined states: not_ready_for_payment to ready_for_payment to completed (or canceled).

Pattern 3: Operations toolkit. Authenticated with API credentials, exposes CRUD operations across a platform’s full API surface. PayPal’s Agent Toolkit and Stripe’s MCP server follow this model. Tools are granular (create_invoice, capture_payment, list_disputes) and map closely to REST API endpoints.

Pattern 4: Gateway server. Sits between agents and existing commerce infrastructure, translating MCP tool calls into platform-specific API calls. commercetools and Salesforce Commerce Cloud use this approach. Adds governance, access controls, and rate limiting at the MCP layer.

---

How UCP and ACP Use MCP as a Transport

Both major commerce protocols treat MCP as a transport layer, not a competitor.

UCP (Google/Shopify) explicitly supports three transports: REST APIs, MCP, and A2A (Agent-to-Agent). A merchant exposes UCP Capabilities as MCP tools, meaning any MCP-compatible agent can interact with UCP-enabled merchants directly. Discovery happens via a /.well-known/ucp JSON manifest that declares supported capabilities, extensions, and payment handlers.

ACP (OpenAI/Stripe) states in its specification that it “can be implemented as a RESTful interface or MCP server.” Merchants wrap their ACP checkout endpoints (/checkouts, /checkouts/:id, /checkouts/:id/complete) as MCP tools. Shared Payment Tokens (SPTs) – single-use, time-bound, amount-restricted – handle payment authorization. The merchant remains merchant of record.

The key insight: MCP is the plumbing. UCP and ACP define the commerce semantics – what tools exist, what data they accept and return, how payments work. Building your commerce system as an MCP server means you can support both protocols from a single implementation by mapping UCP Capabilities or ACP endpoints to MCP tools.

---

Getting Started: Tools, SDKs, and Frameworks

To build an MCP server, use the official Anthropic SDKs:

• TypeScript: @modelcontextprotocol/sdk
• Python: mcp (PyPI)

Both SDKs handle JSON-RPC 2.0 framing, transport negotiation, and tool registration.

To connect agents to MCP servers, every major framework has native support:

Framework	MCP Support
Vercel AI SDK	Native MCP client
LangChain / LangGraph	MCP tool adapter
CrewAI	MCP integration
OpenAI Agents SDK	MCP-compatible tool use
Google ADK	MCP + A2A support

For Shopify-specific development, the Dev MCP server (@shopify/dev-mcp@latest) provides API introspection, documentation search, and code validation directly in your AI-assisted IDE.

For payments, start with Stripe’s MCP server (npx -y @stripe/mcp --api-key=YOUR_KEY) or PayPal’s Agent Toolkit (npm install @paypal/agent-toolkit). Both work in sandbox mode out of the box.

---

Testing and Sandbox Environments

Every reference implementation provides a sandbox path:

• Shopify: Free development stores support Storefront MCP, Checkout Kit, and UCP testing. No production data required.
• Stripe: Standard test mode applies to all ACP integrations. The MCP server accepts test API keys. Use card 4242424242424242 for successful payments.
• PayPal: Set sandbox: true in the Agent Toolkit configuration. Uses PayPal sandbox credentials.
• UCP Playground: Browser-based simulation at ucp.dev/playground. Runs mocked logic – useful for understanding the protocol flow, not for production testing. Add sandbox: true to manifest capability objects during development.
• Salesforce: SLAS sandbox tokens for Commerce Cloud MCP pilot testing.

For end-to-end validation, a community guide documents how to ship an agentic checkout sandbox covering UCP, ACP, and Copilot Checkout in 72 hours (blog.hireninja.com).

---

FAQ

Is MCP the same as UCP or ACP?

No. MCP is a general-purpose transport protocol for connecting AI agents to any tool or data source. UCP (Google/Shopify) and ACP (OpenAI/Stripe) are commerce-specific standards that define what commerce tools should exist and how transactions flow. Both use MCP as one of their supported transport layers.

Do I need to implement both UCP and ACP?

If you want your products discoverable in both Google AI surfaces and ChatGPT, yes. The good news: both can be implemented as MCP servers, so a single MCP server with the right tool definitions can serve both protocols. The tools differ (UCP uses a capability/extension model; ACP uses RESTful checkout endpoints), but the transport is shared.

Does Shopify’s Storefront MCP require authentication?

No. The endpoint at https://{shop}.myshopify.com/api/mcp serves public storefront data without any API key or OAuth token. The Catalog MCP (cross-merchant search) and Checkout MCP require OAuth2 client credentials.

What programming language should I use?

The official MCP SDKs support TypeScript and Python. Shopify’s ecosystem is TypeScript-heavy. PayPal’s Agent Toolkit is TypeScript. Stripe supports both. Google ADK is Python-first. Pick the language that matches your existing stack.

How do payments work through MCP?

MCP itself has no payment semantics – it is a tool protocol. Payments are handled by the commerce layer on top. In ACP, the agent passes a Shared Payment Token (SPT) issued by Stripe. In UCP, payments use the Agent Payments Protocol (AP2) with cryptographic proof of consent. In both cases, the merchant remains merchant of record and retains full control of payment processing.

Can I use MCP without Shopify?

Absolutely. MCP is platform-agnostic. commercetools, Salesforce Commerce Cloud, PayPal, and Stripe all ship MCP servers independent of Shopify. You can build a custom MCP server wrapping any commerce backend – WooCommerce, Magento, a custom system – using the Anthropic MCP SDKs.

What about security and access control?

MCP servers implement authentication at the transport layer. Common patterns include OAuth2 bearer tokens (Shopify Catalog, Salesforce), API keys (Stripe), and client credentials grants (PayPal). For sensitive operations like checkout completion, use idempotency keys and require explicit user consent before processing payments.

---

What to Build First

If you are starting from zero, here is the order that delivers value fastest:

1. Read-only catalog server. Expose product search and detail retrieval as MCP tools. No auth needed, no state to manage. Test with Claude Desktop or Cursor by pointing them at your server. This gets your products into every MCP-compatible agent immediately.

2. Cart and checkout tools. Add create_cart, update_cart, and get_checkout_url tools. Use session IDs for state. Return a hosted checkout URL (your existing checkout page) rather than processing payments in-agent. This covers 80% of the purchase funnel with minimal risk.

3. UCP manifest. Publish a /.well-known/ucp JSON file on your merchant domain declaring your supported capabilities. This makes your store discoverable by Google AI Mode, Gemini, and any UCP-compliant agent.

4. ACP checkout endpoints. Implement the four ACP endpoints (/checkouts POST, GET, PUT, /checkouts/:id/complete) and wrap them as MCP tools. This makes your store accessible from ChatGPT and any ACP-compatible agent.

5. Full checkout in-agent. Once you have payment token handling (Stripe SPTs for ACP, AP2 for UCP), enable complete purchase flows without redirecting to a hosted checkout page.

The critical takeaway: MCP is not one more integration to maintain. It is the integration layer that replaces the need for platform-specific connectors. Build your commerce MCP server once, and every AI agent in the ecosystem becomes a sales channel.

---

References and official repositories:

• MCP Specification: modelcontextprotocol.io
• Shopify Agentic Commerce Docs: shopify.dev/docs/agents
• Shopify Storefront MCP: shopify.dev/docs/apps/build/storefront-mcp/servers/storefront
• Shopify Checkout MCP: shopify.dev/docs/agents/checkout/mcp
• UCP Specification: github.com/Universal-Commerce-Protocol/ucp
• ACP Specification: docs.stripe.com/agentic-commerce/protocol/specification
• PayPal Agent Toolkit: github.com/paypal/agent-toolkit
• Stripe MCP Docs: docs.stripe.com/mcp
• commercetools Commerce MCP: commercetools.com/commerce-platform/commerce-mcp
• Salesforce B2C Commerce MCP: developer.salesforce.com/docs/commerce/b2c-commerce/guide/agentic-mcp-shopper-tools-quick-start.html