跳转到主要内容

MCP 集成

对于模块化组织,所连接的组织必须启用 CRM 模块,并具备集成所需的作用域。CRM 无法访问时,底层 API 会返回带有 module_not_active 的 HTTP 403。请先在 订阅 中解决模块访问权限,再重试;仅更换 API 密钥无法修复此错误。

Scoutello 提供远程 模型上下文协议(MCP) 服务器,用于受控访问组织数据。它与 Scoutello REST API 使用相同的集成、API 密钥、作用域、租户检查、速率限制和记录行为。

当 AI 客户端或代理需要发现并调用 Scoutello 操作作为工具时,请使用 MCP。当应用程序需要传统 HTTP 端点或生成的 OpenAPI 客户端时,请使用 REST。两种接口使用相同的底层数据契约。

连接前​

组织管理员必须在 组织设置 → 开发者/API 中创建集成。创建或轮换密钥时:

  1. 仅选择 MCP 客户端所需的读取和写入作用域。
  2. 在显示时保存完整的 sctl_api_ 密钥。Scoutello 只显示一次。
  3. 将密钥存储在 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.readcontacts_list、contacts_get、contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list、tasks_get、tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list、protocols_get、protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list、opportunities_get、opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list、projects_get、projects_get_by_external_id
projects.writeprojects_batch_upsert(包括参与者更新)
milestones.readmilestones_list、milestones_get、milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list、events_get、events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list、mails_get
mail-drafts.readmail_drafts_list、mail_drafts_get、mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert(仅用于准备人工审核)
tags.readtags_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.readsocial_channels_list
social-posts.readsocial_posts_list、social_posts_get
social-post-drafts.readsocial_post_drafts_list、social_post_drafts_get、social_post_drafts_get_by_external_id
social-post-drafts.writesocial_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。

有关输入示例、上传限制、分页和延迟审核行为,请参阅供人工审核的社交帖子。