Lessons Learned from Building an MCP Server

To build a good MCP server, you shouldn't expect the model to plan on its own. The model only skims the conversation and the tool list and picks the most plausible tool, so the server must clearly present the next call at every step.

In practice, rather than exposing over 100 tools as-is, you converge the flow into 8 core verbs, from office_help to office_read, office_inspect, office_patch, office_table, office_template, office_audit, and word_insert_at_anchor. Tool names are aligned with prefixes like word_*, excel_*, office_* so the chain flows naturally, and you use an activation set that keeps the surface small while widening the accessible scope.

The design principles are also clear.

• A discovery tool should return structured data containing recommended paths, not descriptive text.
• office_help(goal=...) returns the catalog when called with no arguments, and the supported set when the goal is unknown.
• Responses should include breadcrumbs like next_tools and usage to guide the next call.
• Addresses should be kept as values that survive across calls, like anchors, IDs, and paths, instead of line numbers.
• Bundle a mode enum like dry_run, best_effort, safe, strict into a single tool to reduce discovery cost.
• Mutating tools should standardize diagnostics like status, matched_targets, unmatched_targets, next_tools, and always leave behind read-only tools for recovery and audit tools.
• Cache repeated calls, and consider idempotence so that retries are safe even after failures.

Ultimately, if the server does most of the work and the model just follows the breadcrumbs, you can greatly reduce the cost of guessing from schemas and descriptions.