Building Production MCP Servers

Shipping a toy MCP server takes an afternoon. Shipping one that thousands of agents rely on every day — with real data, real latency budgets, and real abuse vectors — is a systems problem. This is the architecture and distribution playbook we use at BuyWhere.

1. Architecture: separate the protocol from the data

The most common mistake is coupling the MCP transport to the data source. A production server has three layers:

Protocol layer — handles JSON-RPC, capability negotiation, and the MCP handshake. This should be thin and standard.
Capability layer — your tools, with input schemas, validation, and rate limiting. This is your product surface.
Data layer — the actual source of truth (your DB, your scraper fleet, your cache). This is where the hard work and the cost live.

Keeping these separate means you can scale the data layer (caching, queueing, sharding) without touching the protocol, and evolve tools without rewriting data pipelines.

2. Tool design: design for the agent, not the developer

An agent calling your tool is not a human reading your docs. Four rules:

Narrow, composable tools beat big ones. search_products(query, market, max_price) is better than get_everything(filters). Agents compose small tools; they struggle with ambiguous mega-tools.
Enums over free text where it matters. market: "SG" | "US" prevents a whole class of hallucinated-region errors.
Return structured data, always. Agents parse fields, not prose. Every response should be a typed object the agent can reason over and pass to the next tool.
Fail loudly and specifically. {"error": "rate_limited", "retry_after": 60} is actionable. A generic 500 is not.

3. Rate limiting and cost control

Production MCP servers get hammered. Agents retry, loops happen, and a single runaway agent can burn your quota. Essentials:

Per-key rate limits at the capability layer (RPM and daily caps).
A free tier generous enough to be useful (we give 1,000 calls/day) but bounded enough to prevent abuse.
Cached reads for hot paths. Product search results that don't change second-to-second should come from cache, not from a live merchant scrape.

4. Distribution: how agents actually find and install you

A server nobody can install is a server that doesn't exist. The production distribution stack:

npm package for one-command installs (npx -y @buywhere/mcp-server).
Official MCP registry listing for discoverability.
Verified client configs for Claude Desktop, Cursor, VS Code, Cline, Windsurf, and Codex — the exact JSON each expects.
A self-service key endpoint so an agent or builder can get credentials without a signup flow.

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

5. Observability: you can't run what you can't see

Track tool call volume, p95 latency, error rates, and per-key usage. When an agent silently stops working, the first question is always "did our server change, or did their call pattern change?" Without per-tool telemetry you're guessing.

The takeaway

The gap between a demo MCP server and a production one is the gap between a script and a service: layered architecture, agent-first tool design, real rate limiting, frictionless distribution, and observability. Get those five right and your server earns daily agent calls instead of sitting in a README.

BuyWhere is a production MCP server searching 288M+ products across SG, SEA, and US markets. Get a key at buywhere.ai/api-keys and read the full API at docs.buywhere.ai.