我们构建MCP服务器的方式是错的

当大多数开发者构建第一个MCP服务器时，他们做了件可预测的事：把REST API拿过来，把每个端点包装成MCP工具。GET /users变成get_users工具。映射是1:1的、机械的，而且是错的。

错在REST API是为阅读文档、理解数据模型、能在脑中串联多个调用的开发者设计的。LLM不是这样工作的。它们使用工具描述，而不是文档。

当你盲目地将REST映射到MCP时，你迫使LLM重建你的API文档本来会给人类开发者的心智模型。有时它成功了。经常失败。当失败时，你责怪LLM而不是工具设计。

根本性的思维转变是：REST端点建模资源。MCP工具应该建模任务。

REST API有GET /users/{id}、GET /users/{id}/orders、GET /orders/{id}/items。三个端点，三次调用，三个需要消费者拼接的响应。

MCP服务器应该有一个get_user_order_summary工具，一次调用返回LLM需要的一切。LLM问"这个用户订了什么？"——给它答案，不是三块拼图。

对API纯粹主义者来说这感觉不对。但消费者不是写干净代码的开发者——而是用更少、更完整的工具调用表现更好的LLM。

在REST API中，端点路径和HTTP方法携带语义信息。GET /users是显而易见的。

LLM不解析URL模式。它们阅读工具描述。你的工具描述是唯一重要的文档。如果模糊，LLM会错误使用工具。

像向一个对你的系统毫无了解的非常字面理解的同事解释工具一样来写描述。准确说明它做什么、返回什么、何时使用以及何时不应使用。

大多数MCP服务器的描述在技术写作课上只能得D。这是你能做的最高杠杆的改进。

我不断看到的模式：一个MCP服务器有search_documents、find_documents和query_documents。三个做几乎相同事情的工具。

对人类开发者来说，区别很明显。对LLM来说，这是三个描述相似的工具，它必须猜测用哪个。大约40%的时间猜错。

工具重叠是MCP可靠性问题的头号来源。解决方案是无情的去重。如果两个工具可以合并，就合并它们。添加参数而不是添加工具。

更少但更强大的工具总是胜过许多专门化的工具。

元教训很简单：MCP工具有不同于REST API的消费者，不同的消费者需要不同的设计。

用真实LLM测试你的工具。不只是"工具是否正确执行？"——而是"LLM是否选择了正确的工具，传递了正确的参数？"

监控LLM在生产中实际如何使用你的工具。你会发现令人惊讶的模式。

最好的MCP服务器不是拥有最多工具的。而是LLM每次第一次尝试就能得到正确答案的。这是唯一重要的指标。