mcp-server-design

name	mcp-server-design
description	Use when designing, building, or debugging a Model Context Protocol (MCP) server in Node/TypeScript. Triggers: stdio JSON-RPC handshake, tool descriptions as discovery surface, lazy startup vs eager catalog loading, telemetry placement, schema design for tool inputs (zod), tool naming conventions for discoverability, error handling that does not leak stack traces, MCP client compatibility (Claude Desktop, Claude Code, Cursor), local resource fetching, secrets and env var handling, distributing as npm + claude mcp add. NOT for MCP client implementation, MCP HTTP transport (different surface), Anthropic Agent SDK building, or non-MCP plugin systems.
license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
metadata	{"category":"AI & Machine Learning","tags":["mcp","model-context-protocol","claude","server","jsonrpc","stdio"],"pairs-with":[{"skill":"skill-architect","reason":"Tool descriptions are a discovery surface exactly like skill descriptions; that skill's activation-engineering discipline applies to every tool an MCP server exposes"},{"skill":"error-handling-patterns","reason":"The isError/sanitization boundary this skill requires at each tool handler is an instance of that skill's error-taxonomy and boundary patterns"}],"provenance":{"kind":"first-party","owners":["port-daddy"]},"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

MCP Server Design

The Model Context Protocol is a JSON-RPC 2.0 dialect over stdio (most commonly). The protocol is small; the design space is in what tools you expose, how you describe them, and how the server starts up. The descriptions are the discovery surface — a tool the client doesn't understand from its description never gets called.

When to use

• Building an MCP server for a domain (skill catalog, code search, internal data).
• Server starts but tools don't appear in the client.
• Tool descriptions are technically accurate but the client never invokes them.
• Latency budget tight; first-call cost too high.
• Need to ship as a single npm command (claude mcp add foo -- npx -y foo-mcp).

Core capabilities

The handshake

client → server  initialize   { protocolVersion, capabilities, clientInfo }
server → client  result       { protocolVersion, capabilities, serverInfo }
client → server  notifications/initialized   (no response)
client → server  tools/list
server → client  result       { tools: [...] }
client → server  tools/call   { name, arguments }
server → client  result       { content: [...], isError? }

The high-level SDK (@modelcontextprotocol/sdk) handles framing. You declare tools; the SDK serializes the schema and dispatches calls.

Minimal server with the SDK

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'mything', version: '1.0.0' });

server.tool(
  'mything_search',
  'Search the catalog. Returns ranked candidates with descriptions only ' +
  '(no full bodies). Pair with mything_load to fetch the chosen item. ' +
  ,
  {
    : z.().(),
    : z.().().().().().().(),
  },
   ({ query, limit }) => {
     results =  (query, limit ?? );
     { : [{ : , : .({ query, results }, , ) }] };
  },
);

 server.( ());