MCP 集成
对于模块化组织,所连接的组织必须启用 CRM 模块,并具备集成所需的作用域。CRM 无法访问时,底层 API 会返回带有 module_not_active 的 HTTP 403。请先在 订阅 中解决模块访问权限,再重试;仅更换 API 密钥无法修复此错误。
Scoutello 提供远程 模型上下文协议(MCP) 服务器,用于受控访问组织数据。它与 Scoutello REST API 使用相同的集成、API 密钥、作用域、租户检查、速率限制和记录行为。
当 AI 客户端或代理需要发现并调用 Scoutello 操作作为工具时,请使用 MCP。当应用程序需要传统 HTTP 端点或生成的 OpenAPI 客户端时,请使用 REST。两种接口使用相同的底层数据契约。
连接前
组织管理员必须在 组织设置 → 开发者/API 中创建集成。创建或轮换密钥时:
- 仅选择 MCP 客户端所需的读取和写入作用域。
- 在显示时保存完整的
sctl_api_密钥。Scoutello 只显示一次。 - 将密钥存储在 MCP 客户端的机密配置或环境配置中,而不是源代码管理系统中。
同一个集成密钥可以调用 REST 和 MCP。无需创建专用于 MCP 的第二个密钥,也不建议这样做。不接受旧版 sctl_mcp_ 密钥。
连接参数
请使用以下参数配置客户端:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
将 YOUR_API_KEY 替换为已保存的集成密钥。客户端配置格式各不相同,但上面的传输方式、URL 和 HTTP 标头保持不变。如果客户端无法设置 Authorization,也可以改为在 x-api-key 中发送密钥。不要同时配置两个标头。
旧版 https://admin.scoutello.com/api/mcp URL 仍作为兼容性别名保留。新连接应使用版本化的 /api/v1/mcp 端点。
验证连接
客户端连接后,首先调用 whoami 工具。该工具会返回当前集成和组织、凭据到期及使用信息、速率限制状态以及已授予的作用域,但不会暴露组织记录。
如果 whoami 指向意外的组织或集成,请断开客户端连接并更正其密钥,然后再调用其他工具。
工具和作用域
MCP 服务器仅公布当前密钥已获授权的工具。仅具有相应读取作用域的客户端无法发现或调用写入工具。
| API 作用域 | MCP 工具 |
|---|---|
contacts.read | contacts_list、contacts_get、contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list、tasks_get、tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list、protocols_get、protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list、opportunities_get、opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list、projects_get、projects_get_by_external_id |
projects.write | projects_batch_upsert(包括参与者更新) |
milestones.read | milestones_list、milestones_get、milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list、events_get、events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list、mails_get |
mail-drafts.read | mail_drafts_list、mail_drafts_get、mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert(仅用于准备人工审核) |
tags.read | tags_list |
经过身份验证的连接始终可以使用 whoami。工具输入和结果遵循其关联 REST 操作相同的架构和响应封装。
contacts_list 接受有边界的 search,可用于名字、姓氏/公司名称、type、status 和 tagIds(包含 1–50 个 ID 的数组,与任一选定标签匹配)。所有搜索词都必须匹配名称字段;所有筛选条件均以 AND 组合。请在每个游标分页请求中继续携带这些筛选条件。例如,{ "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } 可查找匹配的现有账户,而无需扫描完整库存。
与 Scoutello 登录账号关联的非成员 CRM 联系人可读取和引用,但成员资格/账户字段保持隐藏,且联系人编辑仍受保护。仅通过外部链接执行的更新操作可以使用 externalId、其 scoutelloId 以及可选的 externalUpdatedAt 注册可读取的联系人;请省略所有 CRM 字段。后续重试或元数据更新时,请省略 scoutelloId。请参阅联系人边界和关联规则。
安全执行写入操作
批量更新工具可以立即更改 Scoutello 数据。对于相同的集成和外部 ID,它们具有幂等性,但调用方在应用更改前仍应检查目标资源、组织和范围。
将 mode 设置为 validate,可运行匹配和验证而不写入数据。检查结果后,使用 mode: "apply" 再次调用,以接受有效记录。MCP 不提供删除操作。
暂停集成后,使用其密钥的 REST 和 MCP 请求都会被拒绝。轮换会替换其凭据,撤销则会永久停用属于该集成的所有凭据。
故障排查
| 结果 | 检查项 |
|---|---|
401 身份验证错误 | 确认已提供完整密钥,并且请求头使用 Bearer,密钥两侧不要加引号。 |
403 授权错误 | 通过轮换集成密钥授予所需范围,然后使用替换后的密钥更新客户端。 |
MCP URL 出现 404 | 确认 URL 以 /api/v1/mcp 结尾。该 Scoutello 环境可能尚未启用 MCP 服务。 |
429 速率限制错误 | 等待返回的重置时间后再重试。REST 和 MCP 使用相同的集成配额。 |
| 缺少工具 | 使用 whoami 检查密钥范围;不可用的工具会有意从发现结果中省略。 |
有关记录字段、分页、批处理行为和错误信封,请继续参阅 Scoutello API 参考。
连接的项目规划
先创建项目,再创建里程碑,最后使用稳定的集成外部 ID 创建任务和协议。访问新里程碑需要 milestones.read/milestones.write;授予 members.read 后,才能查找可分配的成员。现有凭据的权限范围不会自动扩大。轮换或授予访问权限后,请刷新工具发现结果并检查 whoami。
项目/里程碑的 assignedContacts 使用成员 Customer ID,任务的 assignedScoutelloUserIds 或机会的 ownerScoutelloUserId 使用 User ID。任务/协议引用接受 projectScoutelloId 或 projectExternalId,以及对应的里程碑/机会 ID 对。仅提供里程碑链接时,系统会推断项目;不匹配会拒绝该批次项。项目参与者采用追加式更新,并保留省略的条目。
协议支持无联系人关联的项目/里程碑备注,以及 draft/final 状态。导入这类关联工作时不会产生提示,也不会发送通信。列表工具提供与 REST 相同的、针对实体的项目、状态、分配和截止日期筛选器。请将包括 updatedSince 在内的完整筛选条件传递到每个游标分页中。完整契约以及 null/省略值语义请参阅 API 参考。
验证每个依赖批次,应用后检查每个结果,并回读记录后再将数据填充视为完成。试运行无法解析仅存在于另一个试运行中的父级记录。使用 scoutelloId 重试存在歧义的初始链接时,请先按外部 ID 读取;链接建立后,无法再次使用引导 ID 重放。
销售项目代理指令
为销售项目创建或复用的每个联系人,都必须在 contacts_batch_upsert 中通过 projectScoutelloId 或 projectExternalId 明确引用该项目。在备注或外部 ID 中提及项目并不等于建立成员关系。带有项目引用的联系人写入还需要 projects.write。使用 contacts.read 和 projects.read 回读联系人,并验证 projectParticipations;保留现有成员关系和群组。项目外的普通联系人无需项目引用。
将公司和已验证人员作为独立联系人保存。使用 companyScoutelloId 或 companyExternalId 将人员关联到公司,而不能只使用 companyName。每个批次项中的联系人、公司关系和成员关系更改都是原子的;引用无效时不会留下部分联系人。不要虚构人员或添加来源标签。
使用 mail_drafts_batch_upsert 准备外发邮件,不要将其作为协议正文。明确授予新的 mail-drafts.read 和 mail-drafts.write 范围;准备操作还需要 contacts.read 和 projects.write。现有凭据不会自动获得新权限。使用稳定的外部 ID、用于创建的 expectedVersion: 0、明确的项目/联系人引用、已接受审批人的 User ID,以及已配置的 organization 或 personal 发件人范围。绝不要猜测收件人地址或发件人配置。
将研究内容保存在 content.notes 中;只有 content.subject 和 content.body 属于外发文案。创建草稿时会确保联系人是项目参与者。更新必须使用最新读取结果中返回的版本;已审核或已发送的草稿拒绝编辑。相同的重试会返回原始草稿,不会创建新的审核任务。回读其 reviewUrl、draftVersion、contentHash、审批/发送状态,以及最终的 mailScoutelloId。
只有指定的人员可以通过现有审核界面批准并发送。即使拥有草稿写入权限,集成也无法批准、安排发送或发送邮件。将旧草稿转换时保留原始协议,并交叉引用替换后的协议。队列或不明确的投递失败需要调查,绝不要盲目重发。
社交帖子准备
根据需要授予 social-channels.read、social-posts.read、social-post-drafts.read 和
social-post-drafts.write。members_list(members.read)可查找
审核人员用户 ID。仅在授予相应权限范围时,才会展示社交工具:
| 权限范围 | 工具 |
|---|---|
social-channels.read | social_channels_list |
social-posts.read | social_posts_list、social_posts_get |
social-post-drafts.read | social_post_drafts_list、social_post_drafts_get、social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert、social_media_create_upload、social_media_finalize_upload |
读取频道功能和由 Scoutello 创建的历史记录,上传素材,然后提交包含指定审核人员的完整频道变体。上传工具会返回 HTTP PUT
说明:在 MCP 外部传输原始文件字节,然后使用 { "assetId": "..." } 完成上传。不要在工具参数中嵌入 base64 文件。
新草稿使用 expectedVersion: 0,待处理的修订使用当前版本。mode: "validate" 不会执行写入操作。该工具会返回审核 URL;
只有使用控制面板的人员才能批准发布或排期。MCP 没有用于批准、发布、取消或删除帖子的工具。轮询草稿/历史记录工具,以获取批准状态、拒绝原因以及各频道的投递结果。已审核的草稿若要继续提交提案,则需要新的外部 ID。
有关输入示例、上传限制、分页和延迟审核行为,请参阅供人工审核的社交帖子。