apiVersion: conventions/v1
version: 0.1.0
updated: "2026-06-29"
name: mcp_server_patterns
title: MCP server patterns
scope: general
status: active
summary: MCP servers are thin HTTP shims over a backend API — one tool per capability, types matching the API contract, dual stdio/HTTP transport, stderr-only logging. v2→v4.
appliesTo: ["**/mcp/**", "**/*-mcp/**"]
rules:
  - id: thin_shim
    level: must
    text: No business logic in the MCP server; every tool is one call to the backend API. The backend owns the logic.
  - id: one_tool_per_capability
    level: must
    text: "Separate tools per capability (list_x / get_x / create_x), never one `manage` tool with a mode param."
  - id: shared_types
    level: should
    text: Tool types mirror the backend API contract (shared via the feature's shared/ or a published api-client package), not re-invented.
  - id: dual_transport
    level: should
    text: "stdio for dev/testing; HTTP for prod (bind port + Bearer token auth)."
  - id: layout
    level: should
    text: "Reference layout: src/index.ts (tools) + src/client.ts (HTTP wrapper + env config) + logger to stderr."
  - id: stderr_only
    level: must
    text: Never log to stdout (reserved for the MCP protocol) — logger writes to stderr.