# 一起装 MCP 接入指南（供 AI Agent 使用）

更新：2026-11-05。目标：把一起装接入用户当前使用的 AI Agent，完成用户授权，并用一次真实查询验证连接。

## 连接信息

- 名称：`yqz`
- 服务地址：`https://api.1qizhuang.com/api/mcp/mcp`
- 连接方式：远程 MCP，Streamable HTTP
- 认证方式：OAuth。由用户使用自己的一起装账号登录并选择公司。

## 先确认环境

识别当前宿主及版本、运行环境和它支持的远程 MCP 配置方式。先检查是否已有 `yqz` 连接：已经连接且能正常查询时，无需重复创建；已有配置必须保留其他服务，不要覆盖整个配置文件。不要要求用户提供密码、验证码、访问令牌或其他人的登录状态。

## WorkBuddy 桌面端

WorkBuddy 5.9.3 已观察到的手工入口：左侧「专家·技能·连接器」→ 顶部「连接器」→「自定义连接器」→「添加 MCP」。根据客户端实际界面操作；如果你无法控制相关设置，直接引导用户按这个路径操作，不要声称已经完成。

编辑器首次为空时可使用下面的 JSON；已有其他 MCP 时，把 `yqz` 合并到原有 `mcpServers` 对象中，保留其他服务；已有 `yqz` 时核对现有配置，不要重复添加。

```json
{
  "mcpServers": {
    "yqz": {
      "type": "streamableHttp",
      "url": "https://api.1qizhuang.com/api/mcp/mcp",
      "timeout": 30000
    }
  }
}
```

保存配置后，在 WorkBuddy 中启动或重新连接 `yqz`，根据客户端实际提供的入口发起登录授权。仅保存 JSON 不等于已连接。若没有自动打开浏览器，检查连接状态并使用客户端提供的登录或授权入口；不能代用户操作时，说明具体卡点，请用户在客户端继续。不要编造按钮名称或声称已触发授权。

用户图文指南：https://www.1qizhuang.com/help/workbuddy

## Codex CLI

先运行 `codex mcp get yqz` 检查现有配置；若未配置且当前客户端支持 `codex mcp add --url`，运行：

```sh
codex mcp add yqz --url https://api.1qizhuang.com/api/mcp/mcp
```

然后发起 OAuth 登录：

```sh
codex mcp login yqz
```

让用户在打开的一起装页面登录、选择公司并确认授权。如果无法打开浏览器，使用客户端实际提供的登录提示或 `codex mcp login --no-browser`，让用户按提示完成；不要索取验证码或令牌。如果命令选项不一致，以本机 `codex mcp --help` 和当前版本的官方说明为准。配置或登录失败时报告实际错误，不要删除其他配置或绕过授权。

## 其他 Agent

使用当前客户端支持的远程 MCP 和 OAuth 配置方式，填入上面的服务地址。配置格式和授权入口随客户端变化，不能假定 WorkBuddy 的 JSON 适用于所有客户端。若你无法操作客户端设置，请告知用户所需的服务地址、连接方式和下一步操作。

## 完成授权与验证

1. 由用户在一起装授权页面使用自己的账号登录，选择本次需要查询的公司并确认授权。
2. 按客户端需要重新连接或开启新会话，检查 `yqz` 工具是否已加载。
3. 实际调用 `get_department_tree` 查看权限范围内的组织架构，再调用 `list_projects`，取第一页、每页 5 条，列出工地名称与阶段。若没有数据，说明查询为空即可。
4. 向用户说明实际查询结果及连接状态；公司名称仅在结果或授权信息中明确显示时报告。只报告真实工具返回；授权尚未完成或工具未加载时，说明卡在哪一步和下一步如何操作，不要生成示例数据充当结果。

工具取数范围由用户所选公司和账号权限决定。如需切换公司，使用客户端的重新授权流程；不要猜测或修改 URL 参数来切换公司。