MCP Commerce Server Starter

MCP Commerce Server Starter

Clone-and-deploy boilerplate for a commerce MCP server. Live on Vercel in five minutes. Reachable by Claude, ChatGPT, Gemini, Cursor, and every other MCP-compatible client.

Full build guide (with the why behind every line): How to Build an MCP Server in 2026

What you get

• Product catalog Resource — agents read the full catalog before acting
• search_products Tool — keyword + category + max-price filter
• initiate_checkout Tool — returns order summary + checkout URL
• Optional API-key auth — X-API-Key header, toggle with REQUIRE_AUTH=true
• Health endpoint at /health
• Vercel-ready — one command deploy, free Hobby tier

Stack: Python · FastMCP · FastAPI · Vercel

Quick start (local)

git clone https://github.com/NewPlanetWW/mcp-commerce-startercd mcp-commerce-starter
python -m venv .venv && source .venv/bin/activatepip install -r requirements.txt
python server.py# Server running at http://localhost:8000# MCP endpoint: http://localhost:8000/mcp# Health check: http://localhost:8000/health

Test the health endpoint:

curl http://localhost:8000/health# {"status":"ok","server":"Commerce MCP Server","version":"1.0.0"}

Deploy to Vercel (free)

Requires Node 18+ for the Vercel CLI. No GitHub required — the CLI uploads directly.

npm i -g vercelvercel loginvercel --prod

The CLI prints your production URL. Your MCP endpoint is at:

https://your-project.vercel.app/mcp

Set environment variables in the Vercel dashboard (Settings → Environment Variables):

Wire into Claude Desktop

Option A — Local stdio (fast iteration while building):

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (see full guide for Windows/Linux paths):

{  "mcpServers": {    "commerce-catalog": {      "command": "uvicorn",      "args": ["server:app", "--host", "127.0.0.1", "--port", "8001"],      "env": {        "REQUIRE_AUTH": "false"      },      "cwd": "/path/to/mcp-commerce-starter"    }  }}

Option B — Remote (after Vercel deploy) using mcp-remote:

{  "mcpServers": {    "commerce-catalog-remote": {      "command": "npx",      "args": [        "-y", "mcp-remote@latest",        "https://your-project.vercel.app/mcp",        "--header", "Authorization: Bearer ${MCP_API_KEY}"      ],      "env": { "MCP_API_KEY": "your-secret-key" }    }  }}

Fully quit and relaunch Claude Desktop. Ask: "What products do you have under $100?" — Claude calls search_products and responds with your catalog.

Customize

Replace the sample products

Edit the PRODUCTS list in server.py. Each product needs: sku, name, price, description, availability, category, image_url.

For real inventory, replace the list with a database call:

# server.py — swap PRODUCTS for a live queryimport psycopg2  # or SQLAlchemy, Supabase, etc.
def get_products():    # your DB query here    return [...]
PRODUCTS = get_products()

Add Stripe checkout

Replace the stub in initiate_checkout with a real Stripe session:

import stripestripe.api_key = os.getenv("STRIPE_SECRET_KEY")
session = stripe.checkout.Session.create(    line_items=[{"price": price_id, "quantity": quantity}],    mode="payment",    success_url="https://yourstore.com/success",    cancel_url="https://yourstore.com/cancel",)return {"success": True, "checkout_url": session.url, ...}

The 5 errors you'll hit (and how to fix them)

Covered in the full guide: 30daypivot.com/agentmall_spoke_mcp

1. MCP error -32600 — initialization order violation
2. 422 Unprocessable Entity — Pydantic model vs plain args mismatch
3. 405 Method Not Allowed — missing DELETE in CORS allowed methods
4. stateless_http not set — serverless Vercel requires stateless_http=True
5. ModuleNotFoundError: mcp — wrong package name (mcp[cli], not fastmcp)

Project structure

mcp-commerce-starter/├── server.py          # FastMCP app — resource, tools, middleware, FastAPI mount├── requirements.txt   # Pinned dependencies├── vercel.json        # Vercel deployment config├── mcp.json           # MCP server manifest├── .env.example       # Environment variable template└── README.md

Go deeper

This starter is the code companion to the AgentMall spoke series on 30DayPivot:

• MCP Server Build Guide — the full walkthrough behind this repo
• Agent-Readable Product Data — Schema.org markup so agents find your products without calling the server
• FastAPI Commerce API — REST layer that sits alongside your MCP server
• Free-to-Paid / Stripe Metered Billing — monetize the server you just built
• The AgentMall Roadmap — full picks-and-shovels map of agentic commerce infrastructure

License

MIT