{
  "markdown": "# MCP Commerce Server Starter\n\nClone-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.\n\n**Full build guide (with the why behind every line):** [How to Build an MCP Server in 2026](https://30daypivot.com/agentmall_spoke_mcp)\n\n---\n\n## What you get\n\n- **Product catalog Resource** — agents read the full catalog before acting\n- **`search_products` Tool** — keyword + category + max-price filter\n- **`initiate_checkout` Tool** — returns order summary + checkout URL\n- **Optional API-key auth** — `X-API-Key` header, toggle with `REQUIRE_AUTH=true`\n- **Health endpoint** at `/health`\n- **Vercel-ready** — one command deploy, free Hobby tier\n\nStack: Python · FastMCP · FastAPI · Vercel\n\n---\n\n## Quick start (local)\n\n```bash\ngit clone https://github.com/NewPlanetWW/mcp-commerce-starter\ncd mcp-commerce-starter\n\npython -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\n\npython server.py\n# Server running at http://localhost:8000\n# MCP endpoint: http://localhost:8000/mcp\n# Health check: http://localhost:8000/health\n```\n\nTest the health endpoint:\n\n```bash\ncurl http://localhost:8000/health\n# {\"status\":\"ok\",\"server\":\"Commerce MCP Server\",\"version\":\"1.0.0\"}\n```\n\n---\n\n## Deploy to Vercel (free)\n\nRequires Node 18+ for the Vercel CLI. No GitHub required — the CLI uploads directly.\n\n```bash\nnpm i -g vercel\nvercel login\nvercel --prod\n```\n\nThe CLI prints your production URL. Your MCP endpoint is at:\n\n```\nhttps://your-project.vercel.app/mcp\n```\n\nSet environment variables in the Vercel dashboard (Settings → Environment Variables):\n\n| Variable | Default | Notes |\n|---|---|---|\n| `API_KEY` | `dev-secret-key` | Change before going live |\n| `REQUIRE_AUTH` | `false` | Set `true` to enforce the key |\n\n---\n\n## Wire into Claude Desktop\n\n**Option A — Local stdio** (fast iteration while building):\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS (see [full guide](https://30daypivot.com/agentmall_spoke_mcp#test-with-claude) for Windows/Linux paths):\n\n```json\n{\n  \"mcpServers\": {\n    \"commerce-catalog\": {\n      \"command\": \"uvicorn\",\n      \"args\": [\"server:app\", \"--host\", \"127.0.0.1\", \"--port\", \"8001\"],\n      \"env\": {\n        \"REQUIRE_AUTH\": \"false\"\n      },\n      \"cwd\": \"/path/to/mcp-commerce-starter\"\n    }\n  }\n}\n```\n\n**Option B — Remote (after Vercel deploy)** using `mcp-remote`:\n\n```json\n{\n  \"mcpServers\": {\n    \"commerce-catalog-remote\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-remote@latest\",\n        \"https://your-project.vercel.app/mcp\",\n        \"--header\", \"Authorization: Bearer ${MCP_API_KEY}\"\n      ],\n      \"env\": { \"MCP_API_KEY\": \"your-secret-key\" }\n    }\n  }\n}\n```\n\nFully quit and relaunch Claude Desktop. Ask: *\"What products do you have under $100?\"* — Claude calls `search_products` and responds with your catalog.\n\n---\n\n## Customize\n\n### Replace the sample products\n\nEdit the `PRODUCTS` list in `server.py`. Each product needs: `sku`, `name`, `price`, `description`, `availability`, `category`, `image_url`.\n\nFor real inventory, replace the list with a database call:\n\n```python\n# server.py — swap PRODUCTS for a live query\nimport psycopg2  # or SQLAlchemy, Supabase, etc.\n\ndef get_products():\n    # your DB query here\n    return [...]\n\nPRODUCTS = get_products()\n```\n\n### Add Stripe checkout\n\nReplace the stub in `initiate_checkout` with a real Stripe session:\n\n```python\nimport stripe\nstripe.api_key = os.getenv(\"STRIPE_SECRET_KEY\")\n\nsession = stripe.checkout.Session.create(\n    line_items=[{\"price\": price_id, \"quantity\": quantity}],\n    mode=\"payment\",\n    success_url=\"https://yourstore.com/success\",\n    cancel_url=\"https://yourstore.com/cancel\",\n)\nreturn {\"success\": True, \"checkout_url\": session.url, ...}\n```\n\n---\n\n## The 5 errors you'll hit (and how to fix them)\n\nCovered in the full guide: [30daypivot.com/agentmall_spoke_mcp](https://30daypivot.com/agentmall_spoke_mcp#five-errors)\n\n1. `MCP error -32600` — initialization order violation\n2. `422 Unprocessable Entity` — Pydantic model vs plain args mismatch\n3. `405 Method Not Allowed` — missing DELETE in CORS allowed methods\n4. `stateless_http not set` — serverless Vercel requires `stateless_http=True`\n5. `ModuleNotFoundError: mcp` — wrong package name (`mcp[cli]`, not `fastmcp`)\n\n---\n\n## Project structure\n\n```\nmcp-commerce-starter/\n├── server.py          # FastMCP app — resource, tools, middleware, FastAPI mount\n├── requirements.txt   # Pinned dependencies\n├── vercel.json        # Vercel deployment config\n├── mcp.json           # MCP server manifest\n├── .env.example       # Environment variable template\n└── README.md\n```\n\n---\n\n## Go deeper\n\nThis starter is the code companion to the AgentMall spoke series on **30DayPivot**:\n\n- [MCP Server Build Guide](https://30daypivot.com/agentmall_spoke_mcp) — the full walkthrough behind this repo\n- [Agent-Readable Product Data](https://30daypivot.com/agentmall_spoke_product_data) — Schema.org markup so agents find your products without calling the server\n- [FastAPI Commerce API](https://30daypivot.com/agentmall_spoke_api) — REST layer that sits alongside your MCP server\n- [Free-to-Paid / Stripe Metered Billing](https://30daypivot.com/agentmall_spoke_free_paid) — monetize the server you just built\n- [The AgentMall Roadmap](https://30daypivot.com/agentmall_roadmap) — full picks-and-shovels map of agentic commerce infrastructure\n\n---\n\n## License\n\nMIT\n",
  "bytes": 5480,
  "sha": "60aed764e732e2b087b7a8b059642ffe58c7133387f1644fd9d73509de8ee49a",
  "repo_slug": "newplanetww/mcp-commerce-starter",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_newplanetww_mcp_commerce_start_d63ee6bb/readme"
}