SaaS托管模式
MCP服务由ShopeX或约定的服务方集中托管，客户助手连接托管端点，接入凭证按会话或租户隔离。
- 适合希望快速接入、减少运行环境维护的团队。
- 服务方负责运行、升级、监控与基础可用性。
- 客户仍负责OMS账号权限、凭证生命周期和高风险审批。
- 启用前必须确认正式SLA、网络和数据处理约定。
适合条件：已有正式托管服务，并且企业安全政策允许OMS通过受控网络连接。
OMS MCP · 客户部署指南
同一套安全模型两种部署选择
无论采用SaaS托管还是On-prem私有化，MCP接入都沿用同一套专用凭证、OMS账号权限和部门数据边界；真正不同的是服务运行在哪里、凭证如何传递，以及谁负责运维与审计。
核心建议
个人试用选本机，团队生产选集中服务；部署看托管与网络边界
当前部署文档已经明确两种可落地接法：本机通过npx拉起MCP进程，以及在客户内网部署团队共享的远程MCP服务。
能力边界：远程服务不自动等于公有SaaS。采用ShopeX或第三方托管的SaaS端点前，需要另行确认正式服务地址、SLA、网络访问、日志保留、数据处理和运维责任。
01 · 部署模式
先确定管理归属，再选择技术接法
SaaS与On-prem解决的是托管和责任边界；本机进程与远程服务解决的是MCP客户端如何连接。两个维度不应混为一谈。
On-prem私有化模式
MCP进程运行在个人电脑或客户内网服务器，OMS地址、凭证、日志和运行环境由客户控制。
- 个人试用可使用本机npx进程，几乎不增加运维。
- 团队使用可在内网部署共享MCP服务，集中管理。
- 更容易满足内网访问、日志留存和数据不出域要求。
- 客户负责运行环境、升级、监控、备份和故障处理。
适合条件：已有内网运行环境，或对数据、网络和审计有明确私有化要求。
| 比较维度 | SaaS托管模式 | On-prem私有化模式 |
|---|---|---|
| 服务运行位置 | ShopeX或约定服务方的托管环境。 | 商家个人电脑、客户内网服务器或客户云账号。 |
| 网络路径 | 需要OMS允许受控托管端点访问，并完成网络策略确认。 | 可在客户内网直接访问OMS，网络边界由客户控制。 |
| 凭证方式 | 会话或租户级传递专用CLIENT ID与SECRET，禁止全服务共用一把钥匙。 | 本机写入环境变量，或在内网服务连接建立时按会话传入。 |
| 运维责任 | 服务方负责平台运行；客户负责账号权限、凭证和业务审批。 | 客户负责进程、版本、监控、日志、备份和网络策略。 |
| 数据与日志 | 需在合同或服务说明中明确传输、保留、隔离和删除机制。 | 数据和日志可留在客户环境，按客户制度管理。 |
| 典型使用 | 快速团队接入、标准化托管、无需自建运行环境。 | 开发调试、个人助手、内网团队共享、强私有化客户。 |
| 上线前确认 | 正式端点、SLA、数据处理、网络白名单、审计和退出机制。 | 服务器资源、PHP/Node运行环境、升级责任、监控与应急联系人。 |
02 · OMS前置条件
MCP服务能启动，不代表OMS已经可以被Agent使用
两种部署模式都依赖OMS侧先完成应用、运行环境和专用凭证准备。
安装并启用mcpapi
在OMS安装MCP API授权APP，并执行配置更新，确认/mcp-api/v1/*接口和“MCP接入凭证”入口可用。
PHP升级至8.2
OMS Web和CLI运行环境都要对齐PHP 8.2。低于基线时先升级，再进行MCP连通和业务工具验证。
准备OMS入口与网络
确认形如https://域名/index.php的OMS入口，并根据部署位置配置IP白名单、DNS、证书与访问策略。
配置更新示例：安装APP后，可按环境执行
php app/base/cmd update。生产环境执行前应遵循现有发布、备份和变更审批制度。03 · 专用凭证
两种方式都先领取同一类专用钥匙
接入凭证不是OMS登录密码，实际权限跟凭证所绑定的员工账号、角色和部门范围走。
进入凭证入口
在OMS依次进入“修改密码 → MCP接入凭证”。
创建或轮换
按人员、用途和环境创建专用凭证，避免多人共用。
保存ID与Secret
复制CLIENT ID和CLIENT SECRET。Secret只显示一次。
记录OMS入口
保存OMS Base URL，并确认部署环境能够访问。
安全要求：Secret不得写入普通文档、聊天记录或代码仓库。应存放在企业密码库、密钥管理系统或受控环境变量中；人员离职、权限变化或疑似泄露时立即轮换。
04 · 当前可落地接法
个人使用本机进程，团队使用内网共享服务
以下配置直接来自现有部署说明。示例全部使用占位符，不包含真实客户地址或密钥。
01
本机部署
助手在个人电脑上通过npx自动拉起MCP中间服务，不需要单独准备服务器。
适用与责任
- 个人试用、开发调试、单人桌面助手。
- 凭证写在本地MCP配置的环境变量中。
- 本机用户负责系统权限、配置文件和设备安全。
- 适合先验证查询和低风险工具，再逐步扩展。
MCP客户端配置示例
"shopex-oms": {
"command": "npx",
"args": ["-y", "shopex-oms-mcp-server"],
"env": {
"SHOPEX_OMS_BASE_URL": "https://你们的OMS域名/index.php",
"SHOPEX_OMS_CLIENT_ID": "CLIENT ID",
"SHOPEX_OMS_CLIENT_SECRET": "CLIENT SECRET"
}
}02
内网远程服务部署
在客户内网集中运行一套MCP服务，团队成员的助手连接同一个内网端点。
适用与责任
- 团队共用、集中托管、统一升级、监控和审计。
- 每次连接携带本人的专用凭证，不是服务器共用一把钥匙。
- 服务需部署访问控制、TLS或内网保护、日志和告警。
- 客户IT负责运行环境、可用性和故障处理。
MCP客户端配置示例
"shopex-oms": {
"url": "http://内网MCP地址:8787/mcp",
"headers": {
"X-Shopex-OMS-Base-Url": "https://你们的OMS域名/index.php",
"X-Shopex-OMS-Client-Id": "CLIENT ID",
"X-Shopex-OMS-Client-Secret": "CLIENT SECRET"
}
}05 · 实施路径
从环境准备到生产开放，按五个检查点推进
部署完成只是起点；只有权限、查询、写入批准和结果核对都通过，才算具备生产使用条件。
准备OMS
安装mcpapi、升级PHP 8.2、核对接口和网络。
确定模式
确认SaaS或On-prem责任边界，再选择本机或共享服务。
领取凭证
按账号和环境创建专用凭证，完成安全存储。
先验只读
运行1–2个查询场景，确认权限、部门范围和返回结果。
再开写入
写入先预览、再批准、后回读；验收日志和撤销机制。
06 · 管理边界
部署方式可以不同，安全规则不能打折
无论服务运行在哪里，权限、数据范围、批准机制和凭证生命周期都应保持一致。
专用凭证
每个账号、环境和用途使用可轮换、可作废的CLIENT ID与Secret。
权限跟人走
Agent只能继承所绑定OMS账号已有的角色与部门数据权限。
写入先批准
新增、修改、退款等高风险动作先展示计划和影响，再由人确认。
全过程留痕
记录工具、参数、账号、结果和失败原因，支持审计、追责和复盘。