Building an MCP server — lessons from thunderbit-mcp

Short summary

Designing MCP servers is a product problem, not just protocol translation. Map tools to user intent rather than exposing internal API endpoints, use JSON Schema as the primary contract to make extraction output machine-checkable, and structure errors into actionable categories so agents decide on retry strategy. Lessons from thunderbit-mcp apply broadly to any MCP server wrapping an existing API.

• •Design MCP tools for agent intent, not internal API shape
• •Use JSON Schema as the primary interface contract
• •Create actionable error categories so agents can retry intelligently

Generated with AI, which can make mistakes.