CommerceBridge
A remote MCP server that wraps the live Commerce API — eBay, Shopify, Best Buy, and Etsy marketplace data behind one /v1 contract — as MCP tools any agent (Claude, ChatGPT, etc.) can call directly.
Live: https://commercebridge-isaiahduprees-projects.vercel.app/mcp (Vercel project commercebridge, team isaiahduprees-projects) — 14 tools, verified against real production data (Shopify live; eBay/Best Buy/Etsy honestly gated until their upstream app keys are provisioned). Naming note: the clean commercebridge.vercel.app alias is owned by an unrelated third-party product (a WhatsApp-commerce chatbot) — use the team-scoped URL above, same situation as commerce-api's alias collision.
CommerceBridge does no scraping and holds no data of its own: every tool is a thin, faithful fetch relay to the upstream Commerce API. Whatever that API returns comes back unmodified, including its errors.
Why Authentication: None
This connector's underlying data — eBay/Shopify/Best Buy/Etsy marketplace listings — is fully public and carries zero per-user state. There is no account to log into, nothing to authorize, and nothing to bill per-seat. So, deliberately, CommerceBridge has:
- No OAuth — no login flow, no token exchange, no
/.well-known/oauth-* endpoints
- No Supabase — no user table, no session storage
- No billing — no plans, no usage metering, no upgrade gate
This is the same architectural call this org made for StoreBridge, its sibling connector over App Store/Google Play data: public read-only marketplace data gets the lean, stateless build. It is deliberately leaner than this org's OAuth-based Bridge-family connectors (RemindersBridge, MessagesBridge, etc.), which proxy a signed-in user's own private data and do need auth.
14 tools, one per Commerce API endpoint, grouped by marketplace/engine:
eBay — needs EBAY_CLIENT_ID / EBAY_CLIENT_SECRET on the upstream deployment
| Tool | Endpoint | What it does |
|---|
search_ebay | GET /v1/search | Search live eBay listings by keyword/category across 8 sites (US, GB, DE, AU, CA, FR, IT, ES) |
get_ebay_item | GET /v1/item | Get one eBay item's full detail by REST id or legacy id |
get_ebay_items | GET /v1/items | Bulk-fetch up to 20 eBay items in one call |
search_ebay_sold | GET /v1/sold | Sold/completed-item comps — needs eBay's separately-gated Marketplace Insights API |
Shopify — keyless, live right now
| Tool | Endpoint | What it does |
|---|
search_shopify_products | GET /v1/shopify/products | List any public Shopify store's catalog from its own /products.json |
get_shopify_product | GET /v1/shopify/product | Get one product by handle |
get_shopify_collections | GET /v1/shopify/collections | List a store's collections |
search_shopify | GET /v1/shopify/search | Keyword-filter a store's catalog (title/vendor/type/tags) |
Best Buy — not yet live upstream (route pending redeploy, then needs BESTBUY_API_KEY)
| Tool | Endpoint | What it does |
|---|
search_bestbuy | GET /v1/bestbuy/search | Search Best Buy's US catalog by keyword/category |
get_bestbuy_product | GET /v1/bestbuy/product | Get one product by SKU |
Etsy — not yet live upstream (route pending redeploy, then needs ETSY_KEYSTRING + ETSY_SHARED_SECRET)
| Tool | Endpoint | What it does |
|---|
search_etsy | GET /v1/etsy/search | Site-wide active-listing keyword search |
get_etsy_listing | GET /v1/etsy/listing | Get one listing (only endpoint where views is populated) |
get_etsy_shop | GET /v1/etsy/shop | Get one shop by shop_id or shop_name |
get_etsy_shop_listings | GET /v1/etsy/shop/listings | List a shop's active listings |
Every tool is annotated {readOnlyHint:true, destructiveHint:false, idempotentHint:true, openWorldHint:true} — read-only, non-destructive, idempotent, over an open/external data source.
Expected upstream errors — not a bug
Only Shopify is live today. Every other engine's tool call returns an MCP tool error (isError: true) whose text is the upstream's honest error envelope, verbatim — but the exact error differs by engine, because the upstream commerce-api production deployment currently lags its own source repo:
-
eBay (search_ebay*, get_ebay*) — the route is deployed, but app keys aren't provisioned, so you get:
credentials_required: eBay app credentials required — set EBAY_CLIENT_ID and EBAY_CLIENT_SECRET (free at developer.ebay.com). This API wraps eBay's free Browse API.
search_ebay_sold additionally always returns a 501 not_enabled gate regardless of eBay keys — that endpoint needs eBay's separately-approved Marketplace Insights API, which the base Browse API keys don't grant.
-
Best Buy (search_bestbuy, get_bestbuy_product) and Etsy (search_etsy*, get_etsy*) — as of this writing, the code for these engines exists in the commerce-api source repo but the live production deployment has not been redeployed to include it yet, so these routes 404 at the HTTP layer, verified live:
not_found: No route for GET /v1/bestbuy/search
not_found: No route for GET /v1/etsy/shop
Once commerce-api is redeployed, these will flip to credentials_required (BESTBUY_API_KEY / ETSY_KEYSTRING+ETSY_SHARED_SECRET missing) until those keys are provisioned, then to live data — with zero changes needed here.
CommerceBridge deliberately does not catch, hide, or fake around any of this — the tool handler passes whatever the upstream says straight through as {isError: true, content: [{type:'text', text: '<code>: <message>'}]}, whether that's not_found, credentials_required, or eventually real data.
Configuration
| Env var | Default | Purpose |
|---|
COMMERCE_API_BASE_URL | https://commerce-api-isaiahduprees-projects.vercel.app | Upstream Commerce API base URL. Override to point at a staging/local Commerce API deployment. |
No other configuration. No secrets belong in this repo — API keys live only on the upstream commerce-api deployment.
Run locally
Deploy
That's it — no environment variables are required for CommerceBridge itself (only the upstream commerce-api deployment needs its marketplace app keys). After deploy, point any MCP client at:
https://<your-deployment>.vercel.app/api/mcp
Local smoke test
npm test runs test/smoke.mjs, which connects a real MCP Client to buildServer() from lib/tools.js over an in-memory transport (the exact same server code api/mcp.js serves over HTTP) and checks:
initialize — server identifies itself as commercebridge v1.0.0
tools/list — all 14 tools present, each with an object inputSchema and the expected RO annotations
tools/call → search_shopify_products (store: "allbirds.com") — asserts isError is false and real products come back with marketplace: "shopify" — proves live data flows end-to-end
tools/call → search_ebay — asserts isError is true and the error text contains credentials_required — proves the upstream honest gate surfaces as a clean MCP tool error, not a crash
test/local-server.mjs is a second, thinner check that runs the actual api/mcp.js / api/health.js handlers behind a plain http.Server, to confirm the Vercel-shaped handlers themselves (GET/DELETE → 405, /api/health → {ok, service, upstream}) work outside of the SDK's in-memory transport.
Architecture
lib/tools.js — buildServer(): McpServer + all 14 tool registrations + upstream fetch relay
api/mcp.js — POST /api/mcp — stateless StreamableHTTPServerTransport, no auth
api/health.js — GET /api/health — {ok, service, upstream}
test/ — smoke.mjs (in-memory client/server), local-server.mjs (HTTP handler check)