让你的智能体
连接 TOALDO

开始接入

账户、地址与第一把 Key

将 Codex、WorkBuddy 或其他支持远程 MCP 的智能体连接到你的 TOALDO 账户。客户只需要自己的 TOALDO 账号、API Key 和 MCP 地址，无需安装 TOALDO 服务端文件。

创建 Key

1. 登录 TOALDO 官网，进入账户中心的 Agent & API 页面。
2. 在「功能权限」勾选所需业务。首次验证至少选择「工单查询」，仅查询时无需授予提交权限。
3. 填写便于识别的名称，例如「Codex 办公」或「WorkBuddy 官网业务」；选择连接目标和有效期。
4. 点击「生成 API Key」，把仅显示一次的完整 Key 保存到客户端凭据设置。下文的 YOUR_TOALDO_API_KEY 要在本机替换成完整 Key。

建议为不同客户端分别命名和管理 Key。当前「连接目标」用于显示接入说明，不会将 Key 绑定到某一种客户端。

当前适用范围

本指南面向官网账户入口、企业与合伙人申请、案例授权、人工服务、工单及智能咨询。专业客户端和小程序的生产任务以其实际发布能力为准，不能仅凭接入 MCP 就视为已开通。

连接 Codex

界面配置优先，配置文件可选

在使用 MCP 的 Codex 本机客户端中配置连接。不同版本可能将入口放在设置的「MCP servers」，或「插件」中的 MCP 页面。[1]

1. 添加 MCP 服务器，连接名称填 toaldo，类型选 Streamable HTTP。
2. 地址填写本指南的 MCP 地址。在凭据或请求头设置中配置 TOALDO Key。
3. 若字段叫 Bearer Token，只填完整 Key；若字段叫 Authorization，则填 Bearer 加一个空格再加完整 Key。不要重复添加 Bearer。
4. 保存并使用界面提供的重新连接或重启功能。新建会话，执行第 6 节的只读验收。

配置文件方式

Windows 默认位置：%USERPROFILE%\.codex\config.toml；macOS / Linux：~/.codex/config.toml。若已使用自定义配置目录，以实际目录为准。备份后合并下面这一段；已有同名段落时编辑原段，不要重复，也不要用这几行覆盖整个文件。[1]

[mcp_servers.toaldo]
url = "https://api.toaldoagent.com/api/agent/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOALDO_API_KEY" }
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

组织凭据管理：可选环境变量方式

[mcp_servers.toaldo]
url = "https://api.toaldoagent.com/api/agent/mcp"
bearer_token_env_var = "TOALDO_API_KEY"
enabled = true

由本机安全设置或组织凭据系统提供 TOALDO_API_KEY，变量值只放 Key。确保启动 Codex 的进程能读取它，重新打开客户端后生效。静态请求头与环境变量方式选择一种即可。[1]

连接 WorkBuddy

添加自定义 MCP

在 WorkBuddy 找到 MCP 管理入口。官方指南示例为「插件 → MCP 服务器 → 配置 MCP」；部分版本从「连接器 → 自定义连接器」进入。以当前客户端界面为准。[2][3]

1. 添加自定义远程 MCP，名称填 toaldo，类型选择 Streamable HTTP。
2. 填写 MCP 地址和 Authorization 请求头：Bearer 后加一个空格，再填写完整 TOALDO Key。
3. 保存，确认连接启用；如界面支持单个工具开关，启用本次需要的工具。
4. 新建会话并执行第 6 节验收。只看到旧工具时按第 7 节处理。

完整 JSON 示例

{
  "mcpServers": {
    "toaldo": {
      "type": "streamableHttp",
      "url": "https://api.toaldoagent.com/api/agent/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOALDO_API_KEY"
      },
      "timeout": 30000,
      "disabled": false
    }
  }
}

用户级默认位置：Windows 为 %USERPROFILE%\.workbuddy\mcp.json，macOS 为 ~/.workbuddy/mcp.json。项目级为当前项目的 .workbuddy/mcp.json。[2]

timeout 的 30000 表示 30 秒。disabled: false 表示启用连接。服务器名改变后，工具的命名空间前缀也可能改变；按工具本身的名称发现，不要固定旧前缀。

其他智能体与开发者

按协议接入并读取真实工具定义

其他客户端应支持 HTTPS Streamable HTTP、自定义 Bearer 凭据及 MCP 工具发现。使用相同地址和 TOALDO Key，字段名称按该客户端官方文档填写。当前 TOALDO 接口使用 API Key，不需要向它提交 Codex 或 WorkBuddy 的登录密码。

接入顺序

1. 使用客户端 MCP SDK 完成 initialize 协议协商与初始化流程。
2. 发送 tools/list，读取当前 Key 可用的工具名称和 inputSchema。不要维护固定工具数量或从聊天历史猜参数。
3. 按实际 schema 发起 tools/call。原生客户端可自动处理这些步骤。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "toaldo_web_ticket_list",
    "arguments": {}
  }
}

正常调用先检查 HTTP 状态，再检查 JSON-RPC error；随后检查 result.isError 与 result.structuredContent。不能只凭 HTTP 200 或一段完成提示认定业务成功。

自建系统的 REST 根地址是 https://api.toaldoagent.com/api/agent/v1。具体路径、方法和参数以实际服务契约为准；不要把该地址当作 MCP 地址，也不要将不同产品的 JSON 配置格式混用。

业务权限与 Key 管理

按需要授权，日常加功能复用原 Key

管理已有 Key

1. 官网 Agent & API → API Keys，按名称和标识找到当前客户端使用的 Key。
2. 点击「管理权限」，勾选新增业务并保存。办理类权限可能同时包含必要的查询权限。
3. 原 Key 和 MCP 地址继续使用，重新连接客户端并新建会话验证新增工具。

分清三种维护操作

创建时可选择 30 / 90 / 180 / 365 天。Key 权限只表示允许发起操作，业务仍需满足账号资格、资料、协议和费用等具体条件。

验收与日常使用

验证自己的账号，先从只读查询开始

先确认当前 Key 已有「工单查询」权限。把下面整段发到连接后的新聊天中。此验证不创建业务记录。

请通过当前连接的 TOALDO 原生 MCP 工具做只读连接验收。
先发现工具并读取参数要求，再调用 toaldo_web_ticket_list。
报告实际工具全名、调用是否成功和本次返回条数。
空列表也算成功；没有分页总数字段时，不推断历史总数。
若工具不存在，明确说未执行，不要用其他业务工具代替。
不创建、回复、上传、确认费用，不输出任何凭据。
不要用终端或直接 HTTP 请求冒充原生 MCP 调用。

如何判定通过

• 客户端确实发现并调用了原生 toaldo_web_ticket_list，且业务返回成功；空列表也算通过。
• 工具前缀由连接名称决定。例如 toaldo 与 toaldo_website 可能生成不同的完整工具名。
• 工具数量会随权限和服务更新变化，不以固定 30 / 60 个作为验收标准。
• 要核对多端一致性，可让另一个已授权客户端查询你自己的同一张工单，并核对编号和标题。不要使用他人的测试编号。

使用示例

官网页面是否显示、其他写入业务是否成功，需要分别核对。某一个只读或工单接口通过，不代表所有业务流程都已经完成验收。

故障处理与支持

优先保留证据，区分凭据与工具加载

WorkBuddy 旧工具目录的恢复步骤

1. 确认官网已保存对应 Key 的权限；连接地址为本指南所列 MCP 地址。
2. 在 MCP 管理页关闭并重新启用连接，完全退出 WorkBuddy，重新打开并新建聊天。
3. 若仍未更新：先备份本机 mcp.json，将 mcpServers 下的 toaldo 仅改名为 toaldo_website；保留其内部凭据、地址及其他连接。若新名称已存在，不覆盖。
4. 重新打开客户端，在新会话按工具本名发现并只读验收。改名是故障恢复办法，不是日常授权的必要步骤。仍失败时联系支持。

技术支持可使用同一凭据直接核对服务端 tools/list：服务器有新工具而会话没有，说明差异发生在客户端加载环节；原始请求成功不等于原生调用已通过。排查时不得输出凭据。

联系支持时提供

客户端名称与版本、问题发生时间及所在时区、连接名称、非秘密 Key 标识、脱敏错误码或请求参考号、是否已重新连接。不要提供完整 Key、Authorization、Cookie、Token 或含这些信息的配置文件。

文档依据与版本

• TOALDO Agent & API 管理页
• [1] OpenAI：Codex MCP 配置
• [2] WorkBuddy：MCP 使用指南
• [3] WorkBuddy：连接器配置

文档版本 V1 · 2026-10-01。TOALDO 配置与业务说明以本次官网接入版本为依据，第三方客户端菜单可能随版本变化。