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

#mcp #typescript #ai #tutorial

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.