MCP 接入 AI Agent 指南

让本机 AI Agent 动态发现创业OS真实业务工具，同时复用工作区权限、确认和审计。

一句话接入：在需要接入的项目目录执行 npx -y @xaiverdeng/upos@latest setup --auto，然后重启被配置的 Agent。首次调用工具时在浏览器完成 OAuth 2.0 + PKCE 登录。

MCP 与 MCLI 的区别

入口适合场景是否必需
MCLI（upos）终端、脚本、批处理、受控 Desktop 本地命令可独立使用，不依赖 MCP
MCP bridgeCodex、Claude Code、Cursor 等 Agent 的工具发现与调用仅在需要 Agent 集成时启用
右侧 AI Copilot站内业务页面旁的查询、规划、确认与文件处理日常业务首选，无需安装

一键配置

  1. 进入要接入的项目目录。
  2. 执行：
    npx -y @xaiverdeng/upos@latest setup --auto
  3. 阅读命令输出，确认发现了正确客户端和项目路径。
  4. 重启对应 Agent；首次调用创业OS工具时，在浏览器登录并选择工作区。

如果已全局安装 CLI，也可以执行：

upos setup --auto
upos setup --auto --workspace /path/to/project

支持的客户端

客户端配置范围
Codex、Claude Code、OpenClaw使用客户端原生用户级 MCP 配置入口。
Cursor、VS Code Copilot、OpenCode写入当前项目的 MCP 配置，不扫描或修改其他项目。
Kimi Code、Zed安全合并到各自用户配置；存在同名配置时停止。

DeepSeek 是模型提供商，不是独立 MCP 客户端；它可以由已支持的 Agent 作为模型使用。

命令会写入什么

第一次验证

  1. 在 Agent 中刷新 MCP 工具列表，确认出现创业OS工具。
  2. 先执行只读请求，例如“调用 get_inventory_overview 查询当前工作区库存状态”。
  3. 如果模块未启用或数据源未配置，工具应返回明确状态，不会生成 Mock 数据。
  4. 需要处理 Excel 时，先上传真实文件，再调用 inspect_workbook；任何 update_workbook_cells 写入都应先生成待确认方案。

权限与确认

MCP 只代理服务端当前允许发现的 canonical 工具。每次调用仍绑定用户、设备、工作区和 permission-point scope，并在服务端重新鉴权。客户端显示了工具，不代表当前用户拥有执行权限。

写入、删除和其他高风险工具必须经过 Action Plan 与明确确认。不要在生产工作区用创建、更新或删除工具作为首次连通性测试，也不要把客户端 annotations 当作授权结果。

MCP 工具没有出现

  1. 确认命令是在目标项目目录执行，且输出显示发现了目标客户端。
  2. 检查客户端中是否启用了名为 ssos 的 MCP server。
  3. 重启客户端，触发首次 OAuth 登录并选择有权限的工作区。
  4. 已有同名配置时先人工比较，不要删除或覆盖用户原有配置。
  5. 仍不可用时，记录客户端名称、版本、配置路径和不含凭据的错误信息后联系支持。

相关页面