SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mcp-server-deployment

mcp-server-deployment

部署与运维

查看项目

更新于 10-16 07:48

技能介绍

用途

本技能用于把 MCP 服务器真正运行并分发给真实用户，而不是停留在本地跑通。它针对的典型故障包括：内存中的会话状态在负载均衡器后失效、服务器缺少按工具粒度的可观测性、对智能体依赖的协议接口做一次性大爆炸发布，以及所谓“分发”只到 git clone 为止。

主要能力

  • 交付模式选择：面向技术用户的本地 npm/PyPI 包（stdio 运行，固定安装命令，文档中不使用 npx -y pkg@latest）；面向非技术用户的 MCPB 包（.mcpb，原 .dxt，zip + manifest，一键安装，标记为 "sensitive": true 的密钥存入操作系统钥匙串）；多用户/SaaS 场景的托管 Streamable HTTP 服务；同时支持本地与远程时，共用一层核心工具、按传输方式拆分薄入口。
  • 无状态远程架构：应用节点不保存跨请求状态，会话/工作流状态以会话 id 为键存放在 Redis/Postgres 中并绑定用户身份，使任意节点可在普通负载均衡器后服务任意请求。粘性会话被视为负担而非策略；2026-07-28 规范修订将完全移除协议会话，无状态化也是面向未来的做法。建议先做模块化单体，把慢工具或扇出工具放到队列/worker 之后以保持 p95 工具延迟平稳，仅在确有组织或规模边界时才拆微服务。Serverless 注意事项：约 30 秒执行上限会杀死长工具调用（使用进度与异步模式），长连接 SSE 流需要平台支持。托管 MCP 平台与网关（终止认证/限流/审计）是合理的捷径，但认证要求只是转移而非消失。
  • 健康与发布：存活探针判断进程是否卡死；就绪探针检查真实依赖健康（数据库、缓存、下游 API、认证发现），而非“端口开着”。渐进式交付采用金丝雀或蓝绿；每一步先验证 initialize、认证发现和一个规范 tools/call，再切换更多流量。Streamable HTTP 的按请求特性使金丝雀成本很低。容器方面：精简基础镜像、非 root、固定镜像标签、资源限制。
  • 按工具调用的可观测性：每次工具调用产生一条结构化日志行和一个追踪 span，span 名如 tools.call.<tool_name>；身份/会话作为追踪属性和日志字段，绝不用作指标标签（避免高基数）。关键指标：按工具调用次数、延迟分位数、错误率、isError 率、活跃流/会话数、下游延迟、可计费场景的 token/成本计数。告警项：持续 5xx、认证发现失败、工具超时激增、就绪下降、按调用方成本异常。行为异常（护栏拦截、异常会话时长）是安全信号，由 mcp-server-security 消费。端到端使用 OpenTelemetry；日志需脱敏密钥/PII。
  • 本地安装打包：MCPB 为 manifest + 服务器文件打包，支持 Node/Python/二进制；Claude Desktop 内置 Node 运行时；标记 "sensitive" 的密钥存入操作系统钥匙串。manifest 的 env/config schema 保持最小并在启动时校验。npm/PyPI 需提供可执行入口（npx your-server / uvx your-server），文档给出精确固定的客户端配置 JSON，并让工具代码按调用自包含，使配置错误的安装仍能启动并列出工具（用户在调用时看到配置错误，而不是服务器直接死掉）。服务器文档随包发布：每个工具至少附几个可用调用示例、所需权限/作用域和速率限制。
  • 发布到 MCP Registry： brew install mcp-publisher # 或使用发布二进制 mcp-publisher init # 生成 server.json mcp-publisher login github # 验证 io.github.* 命名空间 mcp-publisher publish server.json（schema：static.modelcontextprotocol.io）指向你的包（npm/PyPI/Docker）和/或远程 URL；npm 包必须在 package.json 中带有匹配的 mcpName 字段以供验证；自定义域名命名空间通过 DNS/HTTP 挑战验证。注册表仅托管元数据，供下游子注册表消费，不对列表做安全审查，且处于预览阶段，可能发生破坏性变更。发布前用 python3 "${CLAUDE_SKILL_DIR}/scripts/check_server_json.py" server.json 校验 manifest。
  • 不破坏客户端的版本管理：服务器/包遵循 semver，工具接口破坏性变更即主版本号；协议采用按会话协商的日期版本，支持当前修订版及真实客户端所需版本，正确发送/期望 MCP-Protocol-Version；工具面保持稳定，优先新增字段而非重命名，移除前在工具描述中给出弃用通知窗口（智能体会读取描述），CI 中做 schema 快照 diff 以捕获意外变更；README 保留兼容性说明：支持的协议修订、已测试客户端、SDK 版本。

使用方式

按工作流分七步执行：选择交付模式、以无状态方式架构远程服务、配置健康与发布、实现按工具调用的可观测性、为本地安装打包、发布到 MCP Registry、以不破坏客户端的方式做版本管理。输出规格为：无状态节点且状态外置；就绪探针基于真实依赖；金丝雀发布验证 init/auth/tool-call；按工具的日志+span+指标，标签低基数且告警可行动；本地包（npm/PyPI 和/或 MCPB）附固定安装文档；在已验证命名空间下从校验过的 server.json 发布注册表条目；README 含 semver 与协议兼容性说明。

适用场景

需要把 MCP 服务器交付给技术用户、非技术用户或多用户 SaaS 场景，并关注水平扩展、可观测性、渐进发布与正式分发的团队。

限制

不适用于：编写/修复服务器代码或传输层（应使用 mcp-server-implementation，含 SSE→Streamable HTTP 迁移）；OAuth/token 接线（mcp-server-auth）；加固/沙箱（mcp-server-security）；评估/负载测试设计（mcp-server-testing）；不涉及 MCP 服务器的通用 Web 应用部署。注册表处于预览阶段，条目/数据在 GA 前可能重置，不应作为唯一分发渠道。企业代理和部分负载均衡器会缓冲或杀死长连接 SSE，需通过真实入口路径测试 GET 流、启用心跳，并在不需要流时优先使用 JSON 响应模式。终止认证/限流的网关并不免除服务器对到达请求的校验——纵深防御而非委托。

注意事项

内存会话状态是水平扩展的头号破坏者，增加副本前先外置状态，或直接无状态并完全跳过会话。客户端配置固定到 @latest 会重新引入你已通过固定版本消除的供应链风险，文档和 MCPB manifest 中也要固定。

参考文件

references/operations.md：参考架构、探针/发布/OTel 示例、MCPB manifest 结构、server.json 结构、网关模式、版本矩阵模板。scripts/check_server_json.py：确定性的注册表 manifest 校验门。