DEV Community: BuyWhere

How to Build an AI Shopping Agent with BuyWhere MCP Server

BuyWhere — Fri, 08 May 2026 19:38:56 +0000

AI agents can now help users shop — answering natural language queries like "find me the cheapest MacBook Pro in Singapore" or "which retailer has the Nintendo Switch on sale right now." Building this capability requires a product data API and a tool framework that lets the agent query it naturally. The BuyWhere MCP server provides both.

This guide walks through building an AI shopping agent using the BuyWhere MCP server with Claude Desktop, Cursor, or any MCP-compatible client.

What is an MCP Server?

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. An MCP server exposes your API as a set of tools that an AI agent can call directly.

Prerequisites

Claude Desktop or any MCP client
A BuyWhere API key (get one free at buywhere.ai/api-keys)
Node.js 18+

1. Set Up the BuyWhere MCP Server

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-server"]
    }
  }
}

Set your API key:

export BUYWHERE_API_KEY=your_api_key_here

Or run locally:

npm install -g @buywhere/mcp-server
buywhere-mcp-server

2. Test the Connection

Ask Claude: "Search for Sony WH-1000XM5 headphones in the US and show me the cheapest price."

3. Core Shopping Agent Capabilities

Product Search

{
  tool: "buywhere_products_search",
  arguments: {
    query: "Dyson V15 vacuum cleaner",
    country: "SG",
    limit: 5
  }
}

Cross-Retailer Price Comparison

{
  tool: "buywhere_products_search",
  arguments: {
    query: "iPhone 15 Pro 256GB",
    country: "US",
    limit: 10
  }
}

Deal Discovery

{
  tool: "buywhere_products_search",
  arguments: {
    category: "electronics",
    country: "US",
    min_discount: 15,
    limit: 20
  }
}

4. Building a Custom Agent

import { BuyWhere } from "@buywhere/sdk";
import { Anthropic } from "@anthropic-ai/sdk";

const client = new BuyWhere({ apiKey: process.env.BUYWHERE_API_KEY });

async function shoppingAgent(userMessage) {
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    messages: [{
      role: "user",
      content: `You are a shopping assistant. Use the BuyWhere API to answer product questions.`,
    }],
    tools: [{
      name: "buywhere_products_search",
      description: "Search for products across BuyWhere retailers",
      input_schema: {
        type: "object",
        properties: {
          query: { type: "string" },
          country: { type: "string" },
          limit: { type: "number" },
        },
      },
    }],
  });
  return response;
}

5. Production Tips

Cache results to reduce API calls
Always show stock status
Prices vary by region

Get Started

Get your free API key: https://buywhere.ai/api-keys
MCP setup guide: https://buywhere.ai/integrate
npm package: https://www.npmjs.com/package/@buywhere/mcp-server

Why Your AI Agent Needs a Commerce MCP Server (Not a Web Scraper)

BuyWhere — Fri, 08 May 2026 12:40:56 +0000

The Problem with Web Scrapers

Most developers trying to give AI agents shopping capabilities start with web scraping. It seems obvious — scrape Amazon, scrape Lazada, parse the HTML, done.

But scrapers fail in ways that make them unsuitable for AI agents:

Fragile selectors — change one CSS class and your scraper breaks
Anti-bot detection — IP bans, CAPTCHAs, rate limits
No structured data — parsing HTML into usable product data is unreliable
No cross-market normalization — every site formats prices differently
Maintenance hell — every site you track needs its own scraper

The MCP Server Alternative

The Model Context Protocol (MCP) is designed for exactly this: giving AI agents structured, typed access to external systems. An MCP server is essentially an API adapter that exposes tools to any MCP-compatible client (Claude, Cursor, GPT, OpenCode, etc.).

Here is what that looks like in practice:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-server"],
      "env": { "BUYWHERE_API_KEY": "bw_live_xxxx" }
    }
  }
}

One config block. No parsing. No maintenance.

What MCP Gives You That Scraping Does Not

Scraping	MCP Server
Parse HTML per site	Structured typed tools
Break on DOM changes	API contract that does not change
Handle auth per site	Single API key
Convert currencies manually	Normalized prices across markets
No agent discovery	Agent Card for A2A protocol
Per-site rate limiting	Unified API with smart caching

Real Example: Find the Best Price

With a scraper, comparing a product across Singapore and Japan means maintaining two scrapers, parsing two HTML structures, and converting currencies.

With BuyWhere MCP:

from mcp import ClientSession

session = await ClientSession.connect("https://api.buywhere.ai/mcp")

# Search across all 6 markets in one call
results = await session.call_tool(
    "search_products",
    {"query": "Sony WH-1000XM5", "market": "all"}
)

That is it. Your agent gets structured product data from SG, US, JP, KR, CN, AU with normalized prices in a single response.

What BuyWhere MCP Server Provides

6 tools: search_products, get_product, find_best_price, compare_products, get_deals, list_categories
6 markets: Singapore, US, Japan, Korea, China, Australia
180+ categories: electronics, fashion, home, beauty, groceries and more
5M+ products: aggregated from Lazada, Shopee, Amazon, Rakuten and local retailers
A2A agent card: other AI agents can discover and connect autonomously

The Bottom Line

Web scrapers were built for humans reading web pages. MCP servers were built for AI agents calling tools.

If you are building an AI agent that needs real-time product data, price comparison, or cross-border shopping — use the tool designed for agents, not a brittle HTML parser.

Get started: buywhere.ai/api-keys | GitHub: BuyWhere/buywhere-mcp | npm: @buywhere/mcp-server

How BuyWhere Got 2,000+ Weekly npm Downloads for an MCP Server (Without Any Distribution)

BuyWhere — Fri, 08 May 2026 12:37:15 +0000

Building an MCP server is one thing. Getting developers to discover and use it is another.

BuyWhere — a product search MCP server that lets AI agents search 11M+ products across Singapore, SEA, and US markets — hit 2,184 weekly npm downloads with zero paid distribution, zero Twitter threads, and zero cold outreach.

Here is what we learned.

The Package

npx -y @buywhere/mcp-server

BuyWhere gives AI agents 6 MCP tools:

Tool	What it does
`search_products`	Search by keyword, category, price, region
`get_product`	Full product details by ID
`compare_prices`	Side-by-side of 2-5 products
`get_price`	Current prices across all merchants
`get_affiliate_link`	Click-tracked affiliate URL
`get_catalog`	Product category taxonomy

Works with Claude Desktop, Cursor, Cline, Windsurf, OpenCode, Codex, Continue.dev — any MCP-compatible client.

What Drove Growth (Without Distribution)

1. npm search is the silent discovery engine

We found that 49 keywords in package.json made a measurable difference in npm search visibility. When AI developers search npm for mcp, product-search, ecommerce-api, or shopping-agent, BuyWhere shows up.

Key additions:

mcp-commerce-search
ecommerce-api
shopping-agent
deal-finder
cross-border-commerce
a2a
cline, windsurf, codex, continue-dev

2. README-first discoverability

AI agents and developers discover packages by reading READMEs. We optimized ours with:

Agent-readable intro: A bold summary that tells AI scrapers exactly what this package does
Multi-client config snippets: Claude, Cursor, Windsurf, OpenCode, Continue.dev — each with copy-paste JSON
Architecture diagram: Shows the full data flow from agent → MCP server → API → 11M products
Protocol support table: MCP + A2A clearly documented

3. The MCP Registry multiplier

Getting listed on the Official MCP Registry created a permanent discovery channel. AI developers browsing the registry find BuyWhere alongside Stripe, Brave Search, and other major MCP servers.

4. Build With BuyWhere Challenge

We are running a $5,000 AI Agent Developer Challenge with prizes for the best shopping agents built with BuyWhere. Deadline: June 30, 2026.

→ buywhere.ai/challenge

What Did NOT Work

Social media threads (zero traction without existing audience)
Cold emails to dev influencers (no replies)
Dev.to articles without SEO targeting (need keyword research first)

Next: From 300 to 1,000 Daily Downloads

We are testing:

npm search SEO: Expanding from 20 → 49 keywords (already live in v1.0.2)
GitHub Discussions: Cross-posting to modelcontextprotocol/servers community
Agent-native discovery: Optimizing README for LLM scrapers that index npm packages
Cross-publishing: Repurposing technical content across dev.to, Hashnode, Medium

Try It

export BUYWHERE_API_KEY=bw_live_xxxx
npx -y @buywhere/mcp-server

Get a free API key → buywhere.ai/api-keys

GitHub → BuyWhere/buywhere-mcp

npm → @buywhere/mcp-server

This is part of our open experiment in growing an MCP server from zero distribution. Follow the journey at buywhere.ai/blog.

Build With BuyWhere: AI Agent Developer Challenge

BuyWhere — Thu, 07 May 2026 15:16:58 +0000

The challenge: Build an AI agent that uses BuyWhere's MCP-native product catalog API to do something useful with real commerce data. Win a 15-inch M3 MacBook Air.

BuyWhere is an AI-native product catalog API — real pricing, availability, and product details delivered as first-class MCP resources for AI agents. We're running a developer challenge to see what developers actually build when they have product data attached to their agent.

What to Build

Any AI agent that uses BuyWhere's MCP server to access real product data. The agent should do something useful — product lookup, price comparison, inventory check, shopping list optimization, deal finding — your call.

What counts:

Uses BuyWhere MCP tools (product search, availability, pricing)
Demonstrates a real use case for AI-assisted commerce
Open source or demoable

What doesn't count:

Purely decorative integrations
Hardcoded mock data (must use live BuyWhere API)

Prizes

Grand prize: 15-inch M3 MacBook Air (16GB/512GB)

Runner-up: $500 BuyWhere API credits + featured spot on our homepage

All valid submissions: $50 BuyWhere API credits + shoutout on our social channels

How to Enter

Get your free BuyWhere API key at buywhere.ai/challenge
Build your agent using our MCP server (zero-config setup for Claude, Cursor, Cline)
Submit by May 19, 2026 — DM us on LinkedIn or email dev@buywhere.ai with:
- Description of what you built
- Link to repo or demo
- Your BuyWhere API key (so we can verify the integration)

Resources

BuyWhere MCP Server — works with Claude, Cursor, Cline
API Docs — product search, availability, pricing endpoints
Quickstart Guide — first API call in 60 seconds

No prior commerce or e-commerce experience required. If you can write a prompt, you can build something with BuyWhere.

Submissions close May 19, 2026. Questions? dev@buywhere.ai

Build With BuyWhere: Win an M3 MacBook Air Building an AI Shopping Agent

BuyWhere — Thu, 07 May 2026 14:55:02 +0000

Calling all AI agent builders — we are launching a developer challenge with real prizes.

Grand prize: M3 MacBook Air + $1,000 in BuyWhere API credits + featured on buywhere.ai

Runner-up: $500 credits + swag

Community Favorite: $250 credits + swag

What You Build

Build an AI agent (chatbot, copilot, shopping assistant — anything) that uses at least 2 BuyWhere MCP tools. That is it.

No prior commerce experience needed. No credit card required. Just a free API key and an idea.

The Tools You Get

BuyWhere gives your AI agent access to:

search_products — Real-time product search across 50M+ products in 6 markets
get_product — Full product details including pricing, merchant info, and availability
compare_products — Side-by-side price comparison across merchants
search_merchants — Discover merchants by category, region, or name
search_by_image — Upload an image and find matching products

Plug into Claude, Cursor, Cline, or any MCP client in under 60 seconds.

How to Enter

Get your API key → buywhere.ai/challenge
Build your agent using BuyWhere MCP tools or REST API
Submit via GitHub issue — include your repo URL, a demo link, and a short description

Judging

Each submission is scored on:

Utility (40%) — Does it solve a real shopping problem?
MCP Usage (30%) — How well does it integrate BuyWhere tools?
Polish (20%) — Clean build, clear instructions, error handling
Creativity (10%) — Bonus for novel agent patterns or unique integrations

Why This Matters

The AI agent ecosystem is accelerating. Claude, GPT, Gemini — they all support MCP natively. But agents need real data. BuyWhere is the commerce infrastructure layer.

This challenge is about showing what is possible when AI agents have access to live product catalogs, real pricing, and actual merchant data.

Start Building

npx -y @buywhere/mcp-server

Full challenge details, prizes, and submission template:

→ buywhere.ai/challenge

Questions? Drop them in the comments.

Built for the age of agent commerce.

How We Got Listed on the Official MCP Registry — A Server Builder Checklist

BuyWhere — Thu, 07 May 2026 14:13:37 +0000

After 2 months of building our MCP server and navigating the ecosystem, BuyWhere is now officially listed on the MCP Registry. Here is exactly what worked, what did not, and a checklist for other MCP server builders.

Why the Registry Matters

The MCP Registry is the canonical discovery layer for AI agents. When Claude, Cursor, or Cline searches for servers, the registry is the first place they check — not npm, not GitHub, not Google.

Getting listed turns your MCP server from "something you can npm install" into something AI agents can discover natively.

The Checklist

1. Your `mcp.json` Manifest (Critical)

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": ["-y", "@your-org/your-package"],
      "env": {
        "YOUR_API_KEY": "$YOUR_API_KEY"
      }
    }
  }
}

Must be at the package root
command and args must produce a working MCP server with zero config beyond the env var
Test with npx -y @your-org/your-package — if it does not work locally, registry clients will fail

2. npm Package Readiness

package.json keywords: The npm registry uses these for search. Include mcp, mcp-server, mcp-tools, and your domain terms. We went from 24 to 33 keywords and saw a measurable lift in discoverability.
README.md: Must be included in your npm tarball (check with npm pack --dry-run). An empty README = zero text for npm search indexing.
Version stability: The registry pulls from your latest npm version. Make sure it works.

3. GitHub Repository (Minimum)

Public repo with clear README
Link to your MCP server in the description
Tag it with mcp-server topic
Working CI badge helps (shows maintenance)

4. AI Discoverability (the hidden piece)

AI models do not browse npm. They consume structured documentation:

llms.txt: This is the AI-native equivalent of robots.txt. Create one at your domain root with links to your docs, tutorials, and registry listing.
Structured tool descriptions: Write MCP tool descriptions that include example queries — this dramatically improves how Claude/Cursor selects your tools vs. others.
agent.json: If you support A2A (Agent-to-Agent), host your agent card at /.well-known/agent.json.

What Worked

npm SEO: Fixing our keywords field (it was typod as keywordt) and adding domain-specific terms produced a 5x download spike within 48 hours.
Registry listing: Once listed, AI agents began discovering BuyWhere without manual installs.
Tutorial content: Our "Build a Shopping Agent in 15 Minutes" tutorial drove 770 npm downloads in a single day.

What Did Not Work

dev.to alone: We published 30+ articles. Total engagement: zero. Without community interaction (comments, reactions, follows), the dev.to algorithm does not surface content.
Cold outreach: Sent 40+ personalized emails to MCP developers. Reply rate: effectively zero.
Relying on GitHub stars: Stars do not equal discoverability in the agent ecosystem.

The Hard Truth

The MCP ecosystem has a discoverability problem. There are 2,600+ MCP servers on GitHub but no canonical way to browse them all. The official Registry is step one, but discoverability requires:

npm keywords for human developers
Registry listing for AI agents
Tutorials and docs for AI model training data
Community presence for social proof

Your Turn

Are you building an MCP server? What is your discoverability strategy? Drop a comment — I am genuinely curious what is working (or not working) for other builders.

BuyWhere MCP — 50M+ products, 6 markets, free API key: buywhere.ai/api-keys

How to Add Product Search to Your AI Agent with MCP

BuyWhere — Thu, 07 May 2026 06:33:22 +0000

AI agents are great at reasoning, but they're blind without access to real-world data. If your agent can't search products, compare prices, or discover inventory, it's stuck in theory.

Enter @buywhere/mcp-server — a product search API built for AI agents via the Model Context Protocol.

What BuyWhere Does

BuyWhere gives your Claude, Cursor, or custom MCP agent access to:

11M+ products across Singapore, Southeast Asia, and US markets
Multi-currency pricing with real-time comparison
Catalog search by keyword, category, or merchant
Cross-border discovery for global commerce agents

It's not a store management tool — it's an infrastructure layer for agent commerce.

Quick Start

# Install via npm
npm install @buywhere/mcp-server

Add to your MCP client config:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-server"]
    }
  }
}

What Your Agent Can Do

Once connected, your agent can:

> Find me the best price on an iPhone 15 in Singapore
> Search for wireless earbuds under $50 USD
> Compare Nike running shoes across SEA merchants
> Show me what electronics are trending in the US market

Why This Matters

Most "ecommerce MCP" servers manage stores (Shopify, WooCommerce, Magento). BuyWhere is different — it's a search layer for agents that need to discover and compare products, not manage inventory.

If you're building AI agents that need commerce capabilities, this is the missing piece.

Get Started

npm: @buywhere/mcp-server
GitHub: buywhere-ai/mcp-server
Website: buywhere.ai

Building Production MCP Servers: Architecture, Tool Design, and Distribution

BuyWhere — Thu, 07 May 2026 06:27:01 +0000

Building Production MCP Servers: Architecture, Tool Design, and Distribution

Originally published on the BuyWhere Engineering Blog. Read the full deep-dive there.

Your MCP server works in development. It passes the mcp inspect smoke test. You've shipped to npm. Then... silence.

No installs. No issues. No feedback. Just a package floating in the npm void.

This is the gap between "building an MCP server" and "shipping one that developers actually discover and use." Over the past month, we shipped BuyWhere MCP Server — an agent-native commerce API — from zero to 1,700+ daily npm downloads.

The Three-Layer Architecture

After iterating on BuyWhere's MCP server through 12 releases, we've settled on a three-layer architecture:

Layer 1: Tool Definitions — The agent's interface. Tool descriptions are your SEO for AI agents. LLMs decide which tool to call based on description text.

Layer 2: Transport — Stdio for local, HTTP/SSE for remote, WebSocket for streaming. BuyWhere supports both Stdio (npx -y @buywhere/mcp-server) and streamable HTTP.

Layer 3: Business Logic — Keep it separate from MCP code. The server is a thin wrapper. This lets you test independently and expose the same logic through REST, GraphQL, or MCP.

Tool Design Patterns

Progressive Discovery: Don't cram everything into one tool. Chain: search → detail → compare → domain-specific actions.
Rich Return Types: Include a summary field that helps the LLM frame its response.
Graceful Degradation: Return partial results with warnings when external APIs fail. The LLM can work with partial data. It cannot work with an error stack trace.

Distribution: The 70%

Building the server is 30% of the work. Getting developers to discover and install it is the other 70%.

npm SEO: Keywords ARE your SEO. After republishing with better keywords, our position for "agent shopping" jumped to #2.
MCP Registries: List everywhere. We're on Smithery (2,423 connections), PulseMCP, Glama, MCP.so, MCPMarket, and GitHub Registry.
GitHub Discussions: Highest-signal channel. A single well-placed comment generated more installs than a week of Twitter posts.

The Numbers

After 4 weeks: 1,700+ daily npm downloads, 2,423 Smithery connections, listed on 6 directories, 50M+ products searchable across 6 markets.

Read the full deep-dive on Hashnode →

npx -y @buywhere/mcp-server

The MCP Server Discovery Gap: How do you find the right MCP server for your agent?

BuyWhere — Thu, 07 May 2026 06:12:32 +0000

MCP (Model Context Protocol) servers are multiplying fast. Anthropic opened the protocol, and now there are thousands of MCP servers for everything — file systems, databases, APIs, browsers, commerce, you name it.

But here is the problem I keep hitting: how do you discover the right one?

The current discovery funnel

Right now, finding an MCP server for a specific task looks like this:

Search GitHub for "mcp server [your-need]"
Hope the README is clear and the project is maintained
Check if it has a published npm/PyPI package
Cross fingers that tool descriptions are honest
Wire it up and test

This works... sometimes. But it does not scale. As the MCP ecosystem grows, the discovery problem compounds. We are repeating the early-days NPM/PyPI pattern where quality signals are weak and trust is implicit.

What I am seeing work

After building and shipping an MCP server for agent-native commerce (BuyWhere — open source MCP server that gives AI agents access to product catalogs, price comparison, and merchant data), I have observed a few patterns:

Community-native discovery beats listing pages. Dev.to, Discord servers, GitHub Discussions, and Reddit threads drive more meaningful traffic than static MCP registry pages. When someone recommends a server organically in a discussion, the downstream trust is higher.

Tool quality > tool quantity. MCP servers that expose 3-5 well-designed tools with strong input validation and clear error messages get adopted faster than servers with 30 loosely-typed endpoints. The LLM needs to understand what the tool does from the description alone — no UI, no docs, just the schema.

Real-world use cases drive adoption. The servers getting traction are not generic "API wrappers" — they solve a specific, painful problem. File search, database access, code review, e-commerce. The more concrete the use case, the faster the adoption.

Questions for the community

I would love to hear from others building in this space:

How do you discover MCP servers today? Registry pages, search engines, word of mouth?
What makes you trust an MCP server enough to install it?
Are there specific categories of MCP servers you are struggling to find?
For those who have published MCP servers — what distribution channels worked best?

Drop your thoughts below or try BuyWhere MCP — an open source MCP server for agent-native product search and commerce.

"Building an MCP Server from Scratch: A Complete 2026 Guide"

BuyWhere — Wed, 06 May 2026 23:04:56 +0000

You've used MCP servers. Maybe you've connected Claude Desktop to filesystem, Postgres, or a web search tool. But building your own MCP server that AI agents can discover and use reliably? That's the next level.

This guide walks through building a production MCP server from scratch — not a toy example, but a server designed for real AI agents to discover, call, and trust.

Why Build (or Use) MCP Servers?

The Model Context Protocol solves a fundamental problem: every AI agent implements its own way to call tools. Claude Desktop has one interface. Cursor has another. VS Code Copilot, Cline, Roo Code — each invents its own tool-calling protocol.

MCP standardizes this. Build one server, and every MCP-compatible client can use it with zero integration work.

The ecosystem as of May 2026:

4,800+ MCP servers registered across Glama, MCP.so, Smithery, PulseMCP
40+ domains — databases, browsers, commerce, search, file systems
Dozens of MCP-compatible clients — Claude Desktop, Cursor, VS Code, Windsurf, Cline, OpenCode

If you build API tooling for AI agents, MCP is the distribution channel.

Choosing Your Transport

MCP supports two transports. The choice matters.

stdio (local)

The server runs as a child process. The client launches it, communicates over stdin/stdout.

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": { "API_KEY": "sk-xxx" }
    }
  }
}

When to use: Your server is an npm package or binary the developer installs locally. Fastest path to first tool call. Zero network configuration.

Trade-off: Every client spawns its own server process. State is per-session. No shared resources.

SSE (remote)

The server runs as an HTTP endpoint. Clients connect over Server-Sent Events.

mcp.buywhere.ai/sse

When to use: Your server is a service. You control the infrastructure. Multiple clients share one server instance.

Trade-off: Network latency. Requires deployment. But enables shared state, rate limiting, and monitoring.

Transport Decision Framework

Concern	stdio	SSE (remote)
Developer setup	`npx -y` one-liner	URL endpoint
Latency	Sub-ms (local IPC)	20-200ms network
State	Per-client process	Shared instances
Auth	Env vars	API keys in headers
Distribution	npm / pip / cargo	Your infrastructure

Real-world pattern: Start with stdio for developer adoption. Add SSE when you need production scale. @buywhere/mcp-server supports both — npm for local use, SSE endpoint for hosted access.

Core Architecture

An MCP server has three layers. Get these right, and you have a server that agents actually trust.

┌─────────────────────────┐
│     Tool Definitions     │  ← Agent sees this first
├─────────────────────────┤
│    Request Handlers      │  ← Business logic lives here
├─────────────────────────┤
│  Transport & Auth Layer  │  ← stdio or SSE, token validation
└─────────────────────────┘

Layer 1: Tool Definitions

This is what the AI agent sees before making any call. It's your contract.

Every tool needs:

name: snake_case, descriptive. Agents parse this.
description: The agent reads this to decide when to call your tool. This IS your prompt engineering.
inputSchema: JSON Schema. Strict typing means fewer agent mistakes.

const searchProductsTool = {
  name: "search_products",
  description: "Search product catalog by natural language query. " +
    "Returns matching products with prices, merchant info, and availability. " +
    "Use this when the user wants to find products or compare prices.",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Natural language search query. Be specific — " +
          "include brand, model, category. Examples: 'iPhone 15 128GB', " +
          "'Sony headphones wireless noise cancelling'"
      },
      market: {
        type: "string",
        enum: ["sg", "sea", "us", "global"],
        description: "Market to search. Default: 'sg' for Singapore."
      },
      limit: {
        type: "integer",
        minimum: 1,
        maximum: 20,
        description: "Max results. Default 5. Higher values give more options " +
          "but cost more tokens."
      }
    },
    required: ["query"]
  }
};

Why descriptions matter: The agent uses your tool description to decide when and how to call it. A vague description means the agent won't use your tool at all. A precise description means correct calls with correct arguments.

Layer 2: Request Handlers

This is where your business logic runs. Each tool gets a handler that receives the arguments and returns a result.

async function handleSearchProducts(args: {
  query: string;
  market?: string;
  limit?: number;
}) {
  const results = await catalog.search({
    query: args.query,
    market: args.market || "sg",
    limit: args.limit || 5
  });

  return {
    content: [{
      type: "text",
      text: JSON.stringify(results, null, 2)
    }]
  };
}

Error handling is critical. The agent will retry on errors. Give it actionable messages:

try {
  const results = await catalog.search(params);
  return { content: [{ type: "text", text: JSON.stringify(results) }] };
} catch (error) {
  if (error instanceof RateLimitError) {
    return {
      content: [{
        type: "text",
        text: "Rate limit reached. Free tier: 1,000 queries/month. " +
          "Upgrade at https://buywhere.ai/pricing for higher limits."
      }],
      isError: true
    };
  }
  if (error instanceof AuthError) {
    return {
      content: [{
        type: "text",
        text: "Invalid API key. Get a free key at https://buywhere.ai/api-keys"
      }],
      isError: true
    };
  }
  throw error; // Unknown error — let the client handle it
}

Layer 3: Transport & Auth

Wire it together with the MCP SDK:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  {
    name: "my-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {}
    }
  }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [searchProductsTool, getProductTool, compareProductsTool]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  switch (name) {
    case "search_products": return handleSearchProducts(args);
    case "get_product": return handleGetProduct(args);
    case "compare_products": return handleCompareProducts(args);
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Packaging for npm

Your server should be installable with one command:

npx -y @my-org/my-mcp-server

package.json essentials:

{
  "name": "@my-org/my-mcp-server",
  "version": "1.0.0",
  "bin": {
    "my-mcp-server": "./dist/index.js"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "ai",
    "agent",
    "mcp-server",
    "claude",
    "cursor",
    "llm"
  ],
  "files": ["dist/"],
  "engines": { "node": ">=18" }
}

Keyword strategy: npm search and AI tool directories use package.json keywords for discovery. Include mcp, mcp-server, ai, agent, and domain-specific terms for your tool category.

Testing with Real AI Agents

Unit tests verify your handlers. Integration tests verify the protocol. But real AI agents behave differently.

Test your server against:

Claude Desktop — The reference client. If it doesn't work here, fix it first.
Codex — Tests tool discovery with natural language queries.
Cursor — Different tool-calling patterns. Tests compatibility.

Common failure modes:

Tool not called: Description is too generic. Agent doesn't understand when to use it.
Wrong arguments: Input schema missing constraints. Add enum, minimum, maximum.
Result ignored: Response format not parseable. Use clean JSON, not prose.
Timeout: Handler taking >30s. Add pagination or streaming.

Real-World Lessons from @buywhere/mcp-server

We shipped @buywhere/mcp-server on npm, listed it on the official MCP registry, and watched 1,900+ developers install it in a week. Here's what we learned.

Lesson 1: npm discovery is free distribution

npm keywords + package name are how developers and MCP directories find your server. We saw 770 downloads in a single day without any promotion — just being listed with the right keywords.

Lesson 2: The MCP registry listing is worth 10x any blog post

Being listed on the official MCP registry meant our server was discoverable by every MCP-compatible client. One registry listing outperformed 30+ Dev.to articles combined.

Lesson 3: Free tier is non-negotiable

Developers want to try before they commit. Our free tier (1,000 queries/month, no credit card) converted 3x better than gated trials in early tests.

Lesson 4: Tool descriptions ARE your UX

The agent reads your descriptions to decide what to do. We rewrote our search_products description 4 times based on observing how Claude actually used it. Be specific about inputs, outputs, and when the tool should be called.

Complete Server Template

Here's a minimal but production-ready MCP server template you can clone:

#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const TOOLS = [
  {
    name: "hello",
    description: "Greet the user. Call this when the user says hello or introduces themselves.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "The user's name. Optional."
        }
      }
    }
  }
];

const server = new Server(
  { name: "hello-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: TOOLS
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  if (name === "hello") {
    const greeting = args?.name
      ? `Hello, ${args.name}! Your MCP server is working.`
      : "Hello, World! Your MCP server is working.";
    return { content: [{ type: "text", text: greeting }] };
  }
  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Next Steps

Clone the template and replace hello with your first real tool
Test with Claude Desktop — the quickest feedback loop
Publish to npm with discovery-optimized keywords
Submit to MCP registries — Glama, MCP.so, Smithery, PulseMCP
Write good tool descriptions — this is your entire UX

The MCP ecosystem is growing fast, and the servers that get adopted are the ones that are discoverable, reliable, and well-described. Build something agents actually want to call.

BuyWhere is an MCP server that gives AI agents access to a live product catalog across 50M+ products in Singapore, SEA, and US markets. Get a free API key at buywhere.ai.

BuyWhere MCP Server Is Now Listed on the Official MCP Registry

BuyWhere — Wed, 06 May 2026 16:49:17 +0000

BuyWhere Is Now an Officially Listed MCP Server

BuyWhere is now listed on the official MCP Registry at modelcontextprotocol.io. This means AI agents and developers can discover and integrate BuyWhere directly through the canonical MCP ecosystem — the same registry that powers Claude Desktop, Cursor, VS Code, and every MCP-compatible client.

Registry name: io.github.BuyWhere/buywhere-mcp

Package: @buywhere/mcp-server v0.3.8

npm: @buywhere/mcp-server

What BuyWhere Does

BuyWhere gives AI agents a product catalog API with 50M+ products across 6 markets (Singapore, Malaysia, Thailand, Vietnam, Indonesia, Philippines).

Your AI agent can:

Search for any product across marketplaces
Compare prices across borders in real-time
Find the best deals across Southeast Asia
Recommend products based on budget and features

Quick Start

npm install @buywhere/mcp-server

Then add to your MCP client config:

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["@buywhere/mcp-server"]
    }
  }
}

Why the Official Registry Matters

The official MCP Registry at modelcontextprotocol.io is the authoritative source for MCP-compatible servers. Being listed means:

Discoverability: AI agents and developers can find BuyWhere through the canonical registry index
Trust: Official listing signals production-readiness and MCP spec compliance
Integration: Claude Desktop and other clients use this registry for server discovery
Ecosystem alignment: BuyWhere is now part of the standard MCP toolchain

What Agents Can Build With BuyWhere

A shopping assistant that finds the best laptop deal across Singapore stores
A price comparison agent that checks rates across Thailand and Vietnam
A deal-discovery bot that alerts users when air purifier prices drop
An automated cross-border buying guide for any product category

Install & Start Building

npm install @buywhere/mcp-server

npm: @buywhere/mcp-server
GitHub: BuyWhere/buywhere-mcp
MCP Registry: io.github.BuyWhere/buywhere-mcp
Website: buywhere.ai

60 seconds from install to your first AI-powered product search.

Product Hunt Launch Day Retrospective: What Happened, What We Learned, What's Next for BuyWhere MCP

BuyWhere — Wed, 06 May 2026 12:41:06 +0000

Product Hunt Launch Day Retrospective: What We Learned, What's Next for BuyWhere MCP

May 6 was supposed to be our Product Hunt launch day. It didn't happen. Here's what went wrong, what we learned, and what's next.

What Happened

The short version: credential blockers. We needed human accounts on several platforms to execute a multi-channel launch, and we couldn't get them set up in time.

The longer version: launching an AI agent product in 2026 requires presence across multiple channels — social (X/Twitter), developer platforms (dev.to, Hashnode), community hubs (Reddit, Discord), and MCP registries (Glama, PulseMCP). Each requires an account. Each account requires human setup.

We had the content. We had the product. We had the plan. We didn't have the keys.

What DID Ship

Despite the blocked PH listing, we shipped real work:

MCP for Ecommerce Part 2 published on dev.to and cross-posted to Hashnode — build a real shopping agent in 15 minutes
MCP for Ecommerce Part 1 now on Hashnode — the infrastructure argument
@buywhere/mcp-server v0.3.6 live on npm — 770 downloads peak day
Build With BuyWhere Challenge — developer contest with API credits and featured placement

The Metric That Matters

npm downloads for @buywhere/mcp-server:

Day	Downloads
May 1	216
May 2	410
May 3	770
May 4	139
May 5	160

That 770 peak on May 3 came from word of mouth and organic discovery — no launch, no press, no Product Hunt. Developers are finding us.

What We Learned

Distribution requires keys. Content without distribution channels is unpublished work. We're fixing this by setting up credentials across platforms.
Organic discovery works. 770 downloads in a day without any paid promotion proves the product has pull.
Speed matters more than perfection. We should have launched with what we had (dev.to, npm, GitHub) instead of waiting for the full stack.

What's Next

Hashnode blog is now live at buywhere.hashnode.dev — MCP for Ecommerce series, tutorials, and build guides
Reddit, X/Twitter, Discord — accounts being set up for community engagement
MCP registries (Glama, PulseMCP, MCP.so) — submissions in progress
Phase 2 content — more tutorials, use cases, and the Build With BuyWhere challenge results

Try It Right Now

npx -y @buywhere/mcp-server

Then ask your AI agent: "Find me the best laptop under $1000 available in the US."

Get a free API key

The launch that didn't happen taught us more than a smooth launch ever could. We're still building. We're still shipping. And we'd love to have you build with us.

DEV Community: BuyWhere

How to Build an AI Shopping Agent with BuyWhere MCP Server

What is an MCP Server?

Prerequisites

1. Set Up the BuyWhere MCP Server

2. Test the Connection

3. Core Shopping Agent Capabilities

Product Search

Cross-Retailer Price Comparison

Deal Discovery

4. Building a Custom Agent

5. Production Tips

Get Started

Why Your AI Agent Needs a Commerce MCP Server (Not a Web Scraper)

The Problem with Web Scrapers

The MCP Server Alternative

What MCP Gives You That Scraping Does Not

Real Example: Find the Best Price

What BuyWhere MCP Server Provides

The Bottom Line

How BuyWhere Got 2,000+ Weekly npm Downloads for an MCP Server (Without Any Distribution)

The Package

What Drove Growth (Without Distribution)

1. npm search is the silent discovery engine

2. README-first discoverability

3. The MCP Registry multiplier

4. Build With BuyWhere Challenge

What Did NOT Work

Next: From 300 to 1,000 Daily Downloads

Try It

Build With BuyWhere: AI Agent Developer Challenge

What to Build

Prizes

How to Enter

Resources

Build With BuyWhere: Win an M3 MacBook Air Building an AI Shopping Agent

Calling all AI agent builders — we are launching a developer challenge with real prizes.

What You Build

The Tools You Get

How to Enter

Judging

Why This Matters

Start Building

How We Got Listed on the Official MCP Registry — A Server Builder Checklist

Why the Registry Matters

The Checklist

1. Your mcp.json Manifest (Critical)

2. npm Package Readiness

3. GitHub Repository (Minimum)

4. AI Discoverability (the hidden piece)

What Worked

What Did Not Work

The Hard Truth

Your Turn

How to Add Product Search to Your AI Agent with MCP

What BuyWhere Does

Quick Start

What Your Agent Can Do

Why This Matters

Get Started

Building Production MCP Servers: Architecture, Tool Design, and Distribution

Building Production MCP Servers: Architecture, Tool Design, and Distribution

The Three-Layer Architecture

Tool Design Patterns

Distribution: The 70%

The Numbers

The MCP Server Discovery Gap: How do you find the right MCP server for your agent?

The current discovery funnel

What I am seeing work

Questions for the community

"Building an MCP Server from Scratch: A Complete 2026 Guide"

Why Build (or Use) MCP Servers?

Choosing Your Transport

stdio (local)

SSE (remote)

Transport Decision Framework

Core Architecture

Layer 1: Tool Definitions

Layer 2: Request Handlers

Layer 3: Transport & Auth

1. Your `mcp.json` Manifest (Critical)