MCP Commerce Server Starter

io.github.NewPlanetWWPublished by GitHub account NewPlanetWWv1.0.0Updated Oct 24, 2026

FastMCP commerce server starter: product catalog, search, and checkout. Deploy to Vercel in 5 min.

VerifiedStreamable HTTPWeb executableDeveloper ToolsBusiness & Commerce

Overview

AI-generated overview

A FastMCP commerce starter server exposing a sample product catalog, product search and a checkout stub, deployable to Vercel.

What you can do
  • Read the full sample product catalog as a resource before acting
  • Search products by keyword, category and maximum price
  • Start a checkout that returns an order summary and a checkout URL
  • Serve a health endpoint for status checks
  • Act as a boilerplate to customize with your own products, database or Stripe checkout
When to use it
Useful if you want a working example of an agent-facing commerce server to clone, extend and deploy, or to try catalog search and checkout flows with sample data. It is a starter, not a production storefront.
Requirements
Runs as a hosted remote endpoint, or locally with Python and the listed dependencies (python server.py, MCP endpoint at /mcp). Deploying to Vercel needs Node 18+ for the Vercel CLI and a Vercel account. Optional API-key auth uses the X-API-Key header, toggled by REQUIRE_AUTH, with the key set in API_KEY.
Before you install
The default API_KEY value is a placeholder that should be changed before going live, and auth is off by default (REQUIRE_AUTH=false). The checkout tool is a stub; wiring in Stripe means handling a STRIPE_SECRET_KEY and real payments. Sample products are hardcoded and must be replaced for real inventory.

Installation

In SourceWeft

  1. Open MCP Commerce Server Starter in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.NewPlanetWW%2Fmcp-commerce-starter/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "commerce-starter": {
      "type": "http",
      "url": "https://mcp-commerce-starter.vercel.app/mcp"
    }
  }
}

README

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)

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

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

bash
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):

VariableDefaultNotes
API_KEYdev-secret-keyChange before going live
REQUIRE_AUTHfalseSet true to enforce the key

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

json
{  "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:

json
{  "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:

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

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

License

MIT

Source: README.md at commit d9ec6db

Tools

0
SourceWeft has not read this server's tools yet.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.