# 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:

```javascript
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](https://mcp.paypal.com)
GitHub: [github.com/paypal/agent-toolkit](https://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.

```typescript
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](https://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](https://ucp.dev/2026-01-23/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](https://blog.hireninja.com/2026/01/30/ship-an-agentic-checkout-sandbox-in-72-hours-ucp-acp-and-copilot-checkout-test-plan-for-founders-jan-30-2026/)).

---

## 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](https://modelcontextprotocol.io)
- Shopify Agentic Commerce Docs: [shopify.dev/docs/agents](https://shopify.dev/docs/agents)
- Shopify Storefront MCP: [shopify.dev/docs/apps/build/storefront-mcp/servers/storefront](https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront)
- Shopify Checkout MCP: [shopify.dev/docs/agents/checkout/mcp](https://shopify.dev/docs/agents/checkout/mcp)
- UCP Specification: [github.com/Universal-Commerce-Protocol/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
- ACP Specification: [docs.stripe.com/agentic-commerce/protocol/specification](https://docs.stripe.com/agentic-commerce/protocol/specification)
- PayPal Agent Toolkit: [github.com/paypal/agent-toolkit](https://github.com/paypal/agent-toolkit)
- Stripe MCP Docs: [docs.stripe.com/mcp](https://docs.stripe.com/mcp)
- commercetools Commerce MCP: [commercetools.com/commerce-platform/commerce-mcp](https://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](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/agentic-mcp-shopper-tools-quick-start.html)