How I Built My First MCP Server for Claude Code (4 Lessons)

Short summary

A developer shares the minimal TypeScript skeleton needed to build MCP servers that expose custom tools to Claude Code over stdio. Four key lessons: tool descriptions must read like teammate instructions, not API docs; handle tool errors gracefully by returning helpful corrective text rather than throwing; ensure schemas constrain bad inputs; and always separate search and fetch tools so the agent can iterate. The mistake that cost the most: descriptions saying 'searches notes' instead of 'search the knowledge base by keyword, returns 5 matches—use this first before get_note.'

• •Build MCP servers to expose custom tools to Claude Code over stdio—no network or auth required
• •Tool descriptions are mini system prompts; write them as instructions to a teammate, not API docs
• •Error handling matters more than schema validation; return helpful guidance instead of exceptions

Generated with AI, which can make mistakes.