用 Python 开发第一个 MCP Server：接口设计原则

先给结论

从一个确定性只读工具开始，使用明确类型和短输出，并让业务异常成为可理解的返回结果。

判断起点

说明工具参数、结构化返回和错误信息的最小设计。MCP 解决的是客户端发现并调用外部能力的连接问题，不替代服务本身的鉴权、安全和业务校验。协议能够连接成功，只说明消息可以往返，不能证明返回数据正确或工具值得信任。

推荐做法

权限评估从最坏副作用倒推：工具能读取什么、能写到哪里、能否联网、能否触发外部操作。只读和写入分开授权，敏感动作保留确认，并使用测试账号或隔离目录演练。权限便利性不能高于数据和服务恢复能力。

核验重点

• 服务声明的工具与实际权限是否一致
• 传输方式和凭据存储是否适合部署环境
• 失败、超时和返回数据是否可追踪

把检查结果写成可复测记录，至少包含日期、版本、环境、输入样例和结果。这样项目升级或需求变化后，团队可以判断原结论是否仍然成立。

进一步验证

共享服务的设计重点从单机可用转向身份、隔离、配额和审计。为每次请求建立可追踪标识，但日志只保留排错所需字段；密钥使用受控存储并支持轮换。上线前用两个不同权限账号验证不能跨边界读取数据。

常见误区

不要把任意 Shell 执行包装成通用工具后直接开放给模型。同时不要把“能够运行”直接解释为“适合生产”，个人试验与长期服务对权限、稳定性、监控和维护的要求不同。

如何形成自己的结论

围绕本文主题准备一个代表性样例，先记录当前方案的基线，再使用候选方案重复同一任务。比较最终正确性、人工修正、耗时、资源或调用成本以及失败恢复情况；如果结果会影响重要数据或线上服务，应先在隔离环境验证。

留下可复查记录

涉及浏览器或登录态时，先判断是否存在更稳定的官方 API。确需浏览器交互时使用专用测试账号，限制下载与上传目录，结束后清理会话。截图、Cookie 和页面内容都可能包含敏感信息，保存策略应在自动化之前确定。

参考来源

• MCP Python SDK

本文根据以上公开项目整理，不复制 README 全文。仓库功能、许可证和维护状态可能变化，使用或分发前请再次查看原始页面。