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-starter

cd mcp-commerce-starter

python -m venv .venv && source .venv/bin/activate pip 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 vercel

vercel login vercel --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 query

import 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 stripe

stripe.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