关于
构建 MCP 服务器以集成外部 API 或服务时使用，支持 Python（FastMCP）或 Node/TypeScript（MCP SDK）。
name: mcp-builder-ms description: "在构建 MCP 服务器以集成外部 API 或服务时使用此技能，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。" risk: unknown source: community date_added: "2026-02-27"
MCP 服务器开发指南
何时使用
在构建 MCP 服务器以集成外部 API 或服务时使用此技能，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。
概述
创建 MCP（模型上下文协议）服务器，使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量取决于它能多好地帮助 LLM 完成现实世界的任务。
Microsoft MCP 生态系统
Microsoft 为 Azure 和 Foundry 服务提供了广泛的 MCP 基础设施。了解这个生态系统有助于你决定是构建自定义服务器还是利用现有服务器。
服务器类型
| 类型 | 传输方式 | 用例 | 示例 |
|------|-----------|----------|---------|
| 本地 | stdio | 桌面应用、单用户、本地开发 | 通过 NPM/Docker 的 Azure MCP Server |
| 远程 | Streamable HTTP | 云服务、多租户、Agent Service | https://mcp.ai.azure.com（Foundry） |
Microsoft MCP 服务器
在构建自定义服务器之前，检查 Microsoft 是否已提供：
| 服务器 | 类型 | 描述 |
|--------|------|-------------|
| Azure MCP | 本地 | 48+ Azure 服务（Storage、KeyVault、Cosmos、SQL 等） |
| Foundry MCP | 远程 | https://mcp.ai.azure.com - 模型、部署、评估、代理 |
| Fabric MCP | 本地 | Microsoft Fabric API、OneLake、项目定义 |
| Playwright MCP | 本地 | 浏览器自动化和测试 |
| GitHub MCP | 远程 | https://api.githubcopilot.com/mcp |
何时使用 Microsoft vs 自定义
| 场景 | 建议 | |----------|----------------| | Azure 服务集成 | 使用 Azure MCP Server（覆盖 48 个服务） | | AI Foundry 代理/评估 | 使用 Foundry MCP 远程服务器 | | 自定义内部 API | 构建自定义服务器（本指南） | | 第三方 SaaS 集成 | 构建自定义服务器（本指南） | | 扩展 Azure MCP | 遵循 Microsoft MCP 模式 |
流程
高级工作流
创建高质量 MCP 服务器涉及四个主要阶段：
阶段 1：深入研究和规划
1.1 理解现代 MCP 设计
API 覆盖 vs. 工作流工具： 在全面的 API 端点覆盖和专门的工作流工具之间取得平衡。工作流工具对特定任务更方便，而全面覆盖给代理灵活性来组合操作。性能因客户端而异——某些客户端受益于组合基本工具的代码执行，而其他客户端使用更高级别的工作流效果更好。不确定时，优先考虑全面的 API 覆盖。
工具命名和可发现性：
清晰、描述性的工具名称帮助代理快速找到正确的工具。使用一致的前缀（如 github_create_issue、github_list_repos）和面向操作的命名。
上下文管理： 代理受益于简洁的工具描述和过滤/分页结果的能力。设计返回聚焦、相关数据的工具。某些客户端支持代码执行，可帮助代理高效过滤和处理数据。
可操作的错误消息： 错误消息应通过具体建议和下一步引导代理找到解决方案。
1.2 学习 MCP 协议文档
浏览 MCP 规范：
从站点地图开始查找相关页面：https://modelcontextprotocol.io/sitemap.xml
然后使用 .md 后缀获取特定页面的 markdown 格式（如 https://modelcontextprotocol.io/specification/draft.md）。
需要审查的关键页面：
- 规范概述和架构
- 传输机制（streamable HTTP、stdio）
- 工具、资源和提示定义
1.3 学习框架文档
Python（FastMCP）：
pip install fastmcp
Node/TypeScript（MCP SDK）：
npm install @modelcontextprotocol/sdk
阶段 2：实现
按照框架文档实现工具、资源和提示。确保：
- 每个工具有清晰的描述和参数模式
- 错误处理返回有用的消息
- 结果格式化为 LLM 友好的格式
阶段 3：测试
- 使用 MCP Inspector 进行交互式测试
- 验证所有工具的输入验证
- 测试错误场景和边界情况
阶段 4：部署
- 本地服务器：打包为 NPM/pip 包或 Docker 镜像
- 远程服务器：部署到云平台，配置认证
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需的输入、权限、安全边界或成功标准，请停下来寻求澄清。
