Lessons on Building MCP Servers

6 hours ago

Focus on a small set of core verbs (e.g., help, read, inspect, patch, audit) to guide model behavior and reduce unnecessary tool calls.
Use consistent naming prefixes (e.g., office_*, word_*) to help models naturally chain related tools and improve planning.
Embed breadcrumbs in every tool response, such as next_tools and usage hints, to make the next step obvious, especially for smaller models.
Implement a discovery tool (like office_help) that returns structured recommendations as data, not prose, and handles unknown inputs gracefully.
Use stable addressing schemes (e.g., anchors, IDs) instead of offsets to maintain context across multiple tool calls and prevent errors.
Consolidate tools with similar functions into modes (e.g., dry_run, safe, strict) to reduce discovery cost and context usage.
Include diagnostics in mutating tool responses (e.g., status, matched_targets) to enable recovery loops and reduce destructive mistakes.
Follow a design checklist emphasizing core verbs, breadcrumbs, consistent naming, safe modes, and idempotent repeat calls for reliable toolchains.

Hasty Briefsbeta