MCP 服务器

Ostorlab 提供一个 MCP 服务器，让 AI 助手和智能体框架可以直接操作您的扫描、漏洞、工单与资产，而无需编写自定义 GraphQL 客户端。

GraphQL API 提供了构建集成的完整平台能力，而 MCP 服务器则为 AI 客户端提供了一组精选的类型化工具，供其自主发现并调用。向您的助手提问 “我的应用最近一次扫描发现了什么？”，它会自动选择合适的工具、串联执行并提供答案。

端点

https://api.ostorlab.co/apis/mcp/{api_key}/

传输方式为 streamable HTTP。API 密钥是 URL 路径的一部分。

Warning

末尾斜杠是必需的。缺少末尾斜杠时，服务器将返回 307 重定向响应。跟随重定向的客户端仍可正常工作，但每个请求都会多消耗一次往返开销；在 POST 请求时不跟随重定向的客户端则会直接失败。

Warning

URL 中的密钥属于敏感凭据。URL 通常会被记录在代理日志、浏览器历史和 Shell 历史中，且 MCP 客户端的配置文件通常以明文保存。请像保护密钥本身一样妥善保管端点 URL。如需停用密钥，请将其吊销 — 设置过期日期无法阻止密钥在此路径上继续使用。

获取 API 密钥

在 Web 应用程序中，导航至 Integrations/API → API Keys（https://report.ostorlab.co/integrations/api）进行创建。密钥的角色决定了 MCP 工具的操作权限 — 详见权限。

连接客户端

大多数客户端需要服务器名称、传输方式和 URL。传输方式为 streamable HTTP，因此在客户端要求指定类型时，请使用 http。

Claude Code

claude mcp add --transport http ostorlab https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/

Claude Desktop、Cursor、VS Code、Windsurf、Zed

这些客户端通过读取 JSON 配置文件进行连接。配置文件的存储路径因客户端和操作系统平台而异 — 请查阅您所用客户端的文档以确定其位置 — 但配置项格式一致：

{
  "mcpServers": {
    "ostorlab": {
      "type": "http",
      "url": "https://api.ostorlab.co/apis/mcp/YOUR_API_KEY/"
    }
  }
}

部分客户端将配置段命名为 servers 而非 mcpServers，部分客户端使用 serverUrl 替代 url。若您的客户端不接受上述配置块，请查阅其文档确认对应的键名 — 最关键的部分是传输方式和 URL。

确认连接正常

让客户端调用一个只读工具，例如列出您的扫描。若密钥无效，服务器将返回 Invalid API Key.。让客户端列出工具列表并不能作为有效的验证手段：无论密钥是否有效，服务器都会返回工具列表。

权限

每个工具在执行任何操作之前都会验证 API 密钥的权限。密钥绑定了一个角色（role），角色授予一组权限操作（action），每个工具都需要特定的权限操作。

工具类型	所需权限
读取扫描、漏洞、工单、评论与检查清单	read
创建或修改工单、评论与检查清单	write
分诊漏洞	write
启动、重新运行与停止扫描	write
列出攻击面资产与标签	attack_surface_read
接受或拒绝发现的资产，以及添加、修改或删除标签	attack_surface_audit
读取和分诊发现队列，以及读取攻击面拓扑图	attack_surface_audit，但拓扑图需要 attack_surface_read
管理 API 密钥、用户与单点登录，读取审计日志，读取和更改组织设置，管理工单智能体、扫描器与扫描器组，创建自动化规则，以及配置、读取或删除大多数集成	admin

未具备所需权限操作的密钥会收到明确的错误信息，而不会返回部分结果。

角色与权限操作的对应关系如下：

角色	read	write	admin	attack_surface_read	attack_surface_audit
reader	是	否	否	是	否
user	是	是	否	是	是
admin	是	是	是	是	是
attack_surface_auditor	否	否	否	是	是

上表反映出两点规则：所有角色都拥有 attack_surface_read 权限，因此任何密钥均可调用 list_assets 和 list_tags。而 attack_surface_auditor 角色既无 read 也无 write 权限，因此仅限于使用攻击面相关工具：它可以读取资产与标签，并能接受、拒绝或编辑它们，但无法查看扫描、漏洞或工单。

若您的组织启用了对象级访问控制，工具将严格遵循该限制，规则与 GraphQL API 密钥一致：

• 扫描与工单 — 非管理员密钥只能查看被显式授予访问权限的具体扫描和工单。
• 资产 — 权限授予基于所有者（owner）而非资产本身。密钥可以查看其获权所有者名下的全部资产。可使用 list_owners 查看当前密钥可访问的所有者，进而了解其能够查看哪些资产。

可用工具

下表按操作对象对工具进行分类整理。每个表格标明了调用该工具所需的权限操作，便于快速判断特定角色的密钥可调用的工具范围。

服务器支持自描述。每个工具均包含其自身的描述和参数列表，客户端在建立连接时会自动读取。若某项工具未在此处列出，可要求您的客户端显示其工具列表 — 这代表您当前连接服务器的权威支持能力。

扫描

工具	权限	说明
list_scans	read	列出扫描，可按 status、asset_id、scan_profile、risk_rating、created_after、archived 过滤。
get_scan	read	获取单个扫描的详细信息。
get_scan_status	read	获取扫描进度、近期状态历史及报告的错误信息。
list_scan_profiles	read	获取组织可运行的扫描配置文件列表，包含 create_scan 所需的准确配置文件名称。
search_store_applications	read	在公共移动应用商店中搜索应用程序，以获取 create_scan 所需的名称与包名。
create_scan	write	针对 Web、网络或移动应用商店目标启动扫描。
create_source_code_scan	write	针对 Git 代码仓库启动扫描。
create_source_code_archive_scan	write	针对已上传的源代码归档文件启动扫描。
create_mobile_file_scan	write	针对已上传的移动应用二进制文件启动扫描。
create_multi_asset_scan	write	启动一次同时覆盖多个目标的综合扫描。
create_mobile_testflight_scan	write	针对通过 TestFlight 分发的 iOS 构建版本启动扫描。
create_autodiscovery_scan	write	跨组织已发现的攻击面启动扫描。
create_rescan	write	使用相同的资产、配置文件、凭据和设置重新运行现有扫描。
stop_scan	write	停止正在运行的扫描。
generate_scan_report	write	为扫描生成 PDF 报告并返回下载链接。

即使 list_scans 可以列出已归档的扫描，get_scan 和 get_scan_status 也不会返回已归档扫描的信息。对已归档扫描调用这两个工具将返回 Scan not found.。

create_scan 接收 web、network 或 mobile_store 的 asset_type，以及相应的目标字段：Web 目标对应 urls，网络目标对应 networks，移动应用商店目标对应 mobile_asset_type 加上 application_name 和 package_name。它还需要 scan_profile_name，该参数必须是 list_scan_profiles 返回的名称之一。若传入组织无权运行的配置名称，请求将被直接拒绝并提示有效名称列表，因此建议先调用 list_scan_profiles。

若目标之前已被扫描过，create_rescan 是更简便的方式。它仅接收现有扫描的 ID 并完整复用其所有配置，避免了配置资产或配置文件时可能出现的错误。新扫描的标题为 Rescan of <原标题>，且即使原扫描被隐藏，新扫描也始终可见。

其他工具用于针对 create_scan 未涵盖的目标类型启动扫描。create_source_code_scan 接收 Git 代码仓库。create_mobile_testflight_scan 接收通过 TestFlight 分发的 iOS 构建版本。create_autodiscovery_scan 无需传入目标 — 它会对组织已接受的所有发现资产进行全面扫描，覆盖范围取决于 list_autodiscovery_assets 中已被纳入清单的内容。create_multi_asset_scan 支持将多种目标组合在一起（Web、网络、代码仓库、应用商店及上传文件）并作为单次扫描运行。

有两个工具接收文件句柄而非目标标识：create_mobile_file_scan 用于扫描移动二进制文件，create_source_code_archive_scan 用于扫描源代码归档文件。两者均接收下文介绍的上传句柄。

上传待扫描文件

由于工具参数为 JSON 格式，无法直接传输文件字节。请先上传文件，然后将获取的句柄传递给扫描工具。

curl -X POST https://api.ostorlab.co/apis/upload/ \
     -H "X-API-Key: <your-api-key>" \
     -F "file=@app.apk"

响应将返回 upload_id，以及服务器记录的文件名、大小和 SHA-256 哈希值，供您验证文件是否完整无误：

{
  "upload_id": "de6024a2-8af5-4e0c-87d2-fdc2c306225f",
  "filename": "app.apk",
  "size": 4171034,
  "sha256": "4ad2930d93c3af606582b26c55ac285485e9623bb508dbf05e5d391b8e4b0969",
  "expires_at": "2026-09-10T09:44:04Z"
}

将该 upload_id 作为 application_upload_id 传递给 create_mobile_file_scan，作为 archive_upload_id 传递给 create_source_code_archive_scan，或放入 create_multi_asset_scan 接收的上传列表中。

关于上传句柄的三个核心特性：

• 句柄归属于上传它的组织。来自其他组织的句柄会被拒绝并提示 Upload not found.，与不存在的句柄表现一致。
• 句柄具有有效期限。过期后调用将被拒绝并提示 Upload has expired.。
• 扫描创建会消耗句柄。扫描一旦创建成功，该句柄即失效；若要运行第二次扫描，需重新上传。若创建调用失败，句柄依然可用，因此重试无需重新上传。

Warning

此处的每个 create_* 工具都会启动真实的扫描任务并消耗扫描配额点数。在客户端发起调用前，请务必确认其展示的目标和配置文件信息。

Warning

generate_scan_report 会持续阻塞直到 PDF 报告生成完成，这可能需要数分钟。响应缓慢并不代表失败，在返回之前请勿超时中断或重复重试。响应返回的是 url 而非文件本身。请通过 HTTPS 访问该 URL，并在 X-API-Key 请求头中携带相同的 API 密钥下载报告。

AI 渗透测试

AI 渗透测试（亦称为智能体深度扫描 / Agentic Deep Scan）属于与常规扫描独立的体系。它的 ID 与常规扫描 ID 不共用，其产出的检测结果称为风险（risks）而非漏洞。

工具	权限	说明
get_agentic_deep_scan	read	单个 AI 渗透测试：其状态、目标、时间与摘要。
get_ai_pentest_usage	read	单个 AI 渗透测试所消耗的 AI Token 使用量。
list_risks	read	AI 渗透测试发现的风险列表，可按渗透测试和严重性过滤。
list_ai_provider_api_keys	read	组织已存储的 AI 提供商 API 密钥列表。

Note

list_vulnerabilities 和 search_vulnerabilities 不会返回风险条目，get_scan 也不会返回 AI 渗透测试。将 AI 渗透测试 ID 传递给 get_scan 会返回 Scan not found. — 这代表“调用工具不匹配”，而非“条目不存在”。仅了解漏洞工具的客户端可能会错误报告 AI 渗透测试未发现任何内容。

漏洞

工具	权限	说明
list_vulnerabilities	read	单个扫描中的发现项，可按 scan_id、risk_rating、kb_detail_id 或所属工单过滤。
search_vulnerabilities	read	跨所有扫描搜索发现项，可按资产、日期范围、严重性、知识库详情与自由文本过滤。
get_vulnerability	read	单个发现项：技术详情、利用详情、CVSS 向量与位置元数据。
update_vulnerability	write	分诊：设置自定义风险评级或 CVSS 向量，或将发现项标记为误报（false positive）或已接受异常（exception）。

当查询范围涉及多个扫描时，请使用 search_vulnerabilities — 例如“该应用程序的所有严重漏洞”、“上个月发现了哪些问题”。仅在已经持有明确扫描 ID 时才使用 list_vulnerabilities。切勿通过遍历扫描列表多次调用 list_vulnerabilities 来回答本可通过单次 search_vulnerabilities 调用解决的问题。

关于 update_vulnerability 的两点注意事项：

• 将发现项标记为误报或异常会作用于关联到该发现项的工单。未关联工单的发现项保持不变，但该调用仍会报告成功。
• 其 all_vulnerabilities 参数会将变更应用于同一扫描中具有相同知识库详情的所有发现项，并重新计算扫描的整体风险评级。其影响范围远大于单个发现项。

每个发现项都包含一个 dna 字段 — 这是基于发现项标题、技术详情与位置派生的数字指纹。只要这三要素未变，后续扫描中发现的相同问题将保持相同的 dna，非常适合在向其他系统导入发现项时进行去重。当多次运行之间的技术详情发生变化时，不保证其保持稳定。

扫描工件

扫描除了产出发现项之外，还会收集运行过程中的衍生数据。以下工具用于读取单次扫描在执行期间捕获的内容。

工具	权限	说明
list_api_endpoints	read	扫描发现的 API 端点。
list_http_traffic	read	扫描捕获的 HTTP 交互流量。
list_http_folders	read	扫描观察到的 HTTP 目录结构。
list_pcap_files	read	扫描生成的数据包捕获文件（PCAP）。
list_ide_files	read	在扫描二进制文件内部发现的文件列表。
list_ide_functions	read	从扫描二进制文件中反编译出的函数列表。
list_ide_logs	read	扫描在驱动应用程序运行时捕获的设备端运行时日志。
list_call_ui_nodes	read	移动应用扫描在驱动应用程序时到达的界面屏幕。
list_stack_traces	read	扫描在驱动应用程序时记录的调用堆栈跟踪。

扫描捕获的数据类型取决于所执行的扫描类型。Web 扫描包含 HTTP 流量而无反编译二进制；移动端扫描则可能兼具两者。结果为空表示该次扫描未收集到此类数据，并不意味着扫描失败。

工单

工具	权限	说明
list_tickets	read	工单列表，可按 status、priority、assigned_email、agent、tag、title、created_since、modified_since 过滤。支持排序并带有 limit。
get_ticket	read	单个工单详情，通过 ID 或标识键（例如 os-1234）获取。
create_ticket	write	创建工单，可选择指定标签、经办人、工单智能体及截止日期。
update_ticket	write	修改上述任一字段。
delete_ticket	write	删除工单。不可逆。

评论与检查清单

工具	权限	说明
list_comments、create_comment、update_comment、delete_comment	read 用于列出，其余操作需要 write	工单上的评论对话流。
list_checklists、create_checklist、update_checklist、delete_checklist	read 用于列出，其余操作需要 write	附加到工单的修复检查清单。
create_checklist_item、update_checklist_item、delete_checklist_item	write	单个检查清单项。

Note

向已分配工单智能体的工单添加评论将触发一次新的智能体运行。

通过 MCP 创建的评论不会关联作者信息，因为服务器鉴权依据的是 API 密钥而非个人用户账户。这些评论在 Web 应用中显示为无作者。

工单智能体

工单智能体是平台可在工单上运行以执行修复工作的 AI 智能体。可通过为工单分配智能体来指派修复任务。

工具	权限	说明
list_ticket_agents	read	可分配工单的智能体列表，包含 enabled 标志及各智能体运行内容的摘要。
assign_ticket_agent	write	为工单分配智能体，这将立即启动一次智能体运行。
create_ticket_agent	admin	添加新智能体，可选择指定其应使用的运行定义。
update_ticket_agent	admin	修改智能体的名称、描述或运行定义。
delete_ticket_agent	admin	删除智能体。

Warning

分配智能体会立即启动运行，且运行过程无法撤销。工单一旦绑定智能体，后续在该工单上的每条新评论都会启动另一次运行。请检查响应中的 agent_run 字段以确认运行是实际启动还是被跳过 — 切勿盲目假定其已开始。

删除智能体将清除已分配该智能体的所有工单上的分配关联。工单本身将被保留，但其智能体设置会被置空；恢复关联的唯一途径是创建新智能体并逐个工单重新分配。删除响应中包含 unassigned_tickets 统计计数，在判定智能体是否闲置前请先核实该数值。智能体的运行定义也会被销毁，且在删除前无法完整读回 — list_ticket_agents 仅返回脱敏后的摘要信息。参数的具体取值绝不会返回，因此无法利用这些工具读取智能体的凭据配置。

工单流

工单流（Stream）用于对工单进行逻辑分组，以便在 Sprint、版本发布或特定项目中进行统筹跟踪。

工具	权限	说明
list_ticket_streams	read	工单流列表，可按状态、名称子字符串或流 ID 过滤。
get_ticket_stream	read	单个工单流的详细信息。
create_ticket_stream	write	创建工单流，可选择指定负责人、成员、关联工单及时间范围。
update_ticket_stream	write	修改上述任一字段。
delete_ticket_stream	write	删除工单流。其引用的工单和用户账户将被保留。

member_emails 和 ticket_ids 采用整量替换而非增量追加模式。如需新增一名成员，必须传入包含现有成员与新成员的完整列表。

资产与资产清单

工具	权限	说明
list_assets	attack_surface_read	攻击面资产列表，可按 asset_type、owner_id、search、tags 过滤。
create_asset	write	在所有者名下注册单个资产 — 域名、应用程序、IP 地址、代码仓库或通用节点。
update_asset	write	修改单个资产的所有者、位置、颜色标记、备注、CIA 需求或标签。
delete_asset	write	从资产清单中移除单个资产。
list_fingerprints	attack_surface_read	在整个资产清单中观察到的技术指纹。
list_ports	attack_surface_read	在整个资产清单中观察到的不同开放端口。
list_protocols	attack_surface_read	在整个资产清单中观察到的不同协议。

资产由 asset_type 和 asset_id 二元组共同标识，而非单独依赖 ID。每种资产子类型存储在各自独立的数据表中，因此相同的数值在不同子类型中指代不同的资产。update_asset 和 delete_asset 均接收此二元组，list_assets 返回的也是该二元组。

在同一所有者下，create_asset 具备幂等性：重复注册已存在的资产将返回现有行并将 created 标志置为 false，而不会报错。若注册的标识已存在于其他所有者名下，请求将被拒绝并返回通用错误，从而防止通过写入探测不可见资产。

删除资产不会删除其关联的扫描或发现项。扫描的资产关联会被清除，扫描记录本身完整保留。

update_asset 中的 tags 参数会对资产标签进行整量替换，而不会执行合并。

list_fingerprints、list_ports 和 list_protocols 用于对资产清单进行聚合汇总。各项工具分别返回当前密钥可访问资产中观察到的不同技术指纹、端口和协议，无需逐页遍历 list_assets 即可解答“我们运行了什么技术”及“暴露了哪些服务”。

所有者

所有者代表一个团队，是对象级访问控制的授权边界。启用对象级访问控制时，密钥仅能查看其可访问所有者名下的资产。在向所有者分配资产前，必须先创建该所有者。

工具	权限	说明
list_owners	read	组织的所有者列表，可按名称子字符串过滤。
create_owner	write	创建所有者，需提供名称、所有权类型，可选择指定联系人和父级。
update_owner	write	重命名所有者、修改其类型、重新分配联系人或将其移动到其他父级下。
delete_owner	write	删除所有者。

ownership_type 的取值必须为 rejected、acquisition、third_party_service 或 internal 之一。

Warning

当所有者名下仍有资产，或仍有已发现但未确认的候选资产指向该所有者时，delete_owner 将拒绝删除。删除操作绝不会级联传播 — 资产必须得到保留，拒绝删除正是为了保护资产。此机制旨在防范严重风险：若在仍挂载资产的情况下删除了所有者，通过该所有者配置的所有对象级访问授权都将随之失效，进而导致被授权密钥悄然失去对这些资产的可见性。请先重新分配或删除名下资产，然后再删除所有者。

在启用对象级访问控制的情况下，非管理员密钥调用 list_owners 将返回已获授权的所有者及其父级所有者。管理员密钥可查看组织中的所有所有者。因此，返回空结果意味着组织完全未配置所有者，或者当前密钥无权访问任何所有者。

资产位置

位置是一个带标签、支持嵌套的站点或区域层级，用于对资产进行逻辑分组归类。它仅作为逻辑标签使用，不代表扫描器，也不会决定扫描的实际执行节点。

工具	权限	说明
list_asset_locations	read	为组织配置的位置列表。
create_asset_location	write	创建位置，需提供名称，可选择指定地址和父级位置。
update_asset_location	write	重命名位置、修改其地址或将其移动到其他父级下。
delete_asset_location	write	删除位置。

create_asset_location 具备幂等性：传入相同名称、地址和父级位置时，将原样返回现有记录并将 created 标志置为 false。

若仍有资产绑定到该位置，或该位置下仍嵌套有子位置，delete_asset_location 将拒绝删除。删除操作绝不级联：关联资产和子位置均会得到保留。请先移走或解绑它们，然后再删除位置。

发现的资产

攻击面资产发现引擎会自动提出候选资产。候选资产将留存在审核队列中，直到人工将其纳入资产清单或予以驳回。

工具	权限	说明
list_autodiscovery_assets	attack_surface_audit	待处理的发现队列，可按键模式、候选类型、评分范围和所有者过滤。
accept_autodiscovery_asset	attack_surface_audit	将一个候选资产晋升并纳入资产清单。
reject_autodiscovery_asset	attack_surface_audit	驳回并忽略一个候选资产。
assign_potential_node_owner	attack_surface_audit	为待处理的候选资产指定所有者。
compute_potential_assets	attack_surface_audit	立即触发重新计算发现队列，无需等待下一次计划任务。
suggest_autodiscovery_domains	attack_surface_audit	根据公司的自然语言描述，推断并建议其可能拥有的域名。
get_attack_surface_graph	attack_surface_read	获取围绕一个或多个起点的攻击面拓扑图邻域。

Warning

接受候选资产将使该资产变为可扫描且计费对象 — 它会加入资产清单，成为扫描目标，并计入组织的套餐配额。接受与拒绝工具特意设计为仅接收单一明确的 ID，不支持批量或过滤模式，以防止模型在一次调用中将整个队列盲目导入资产清单。请务必逐一审核候选资产。

驳回一个键未在现有清单中匹配任何资产的候选资产时，系统会记录该键，以便后续的发现扫描停止重复推荐。若驳回的候选资产的键已经匹配到了现有清单资产，则仅将其从队列中移除，后续发现任务仍可能再次推荐。

assign_potential_node_owner 用于在候选资产被接受之前预先设定其所属的所有者，确保资产在纳入清单时已明确归属团队。该操作不会自动接受候选资产 — 资产仍留在队列中，直到针对其调用 accept_autodiscovery_asset。

get_attack_surface_graph 用于解答“该节点与哪些对象相连”。为其传入一个或多个起点，它将从起点向外遍历，并以两个扁平列表返回所达邻域 — 节点列表以及连接它们的边列表。该遍历是有边界约束的，因此位于图密集区域的起点会返回受限的邻域结果，而非所有可达的全部节点。

compute_potential_assets 用于按需手动触发资产发现，无需等待下一次例行任务。若调用时已有发现任务在运行，调用将直接接入该任务而不是开启第二次运行，因此重复调用是安全的。

资产发现配置

资产发现受一段描述组织资产范围的提示词引导，以确保推荐的候选对象切实与您的业务相关，避免混入同名无关公司的资产。

工具	权限	说明
get_attack_surface_agent_config	read	获取指导组织资产发现的提示词配置。
create_attack_surface_agent_config	write	设置该提示词。
update_attack_surface_agent_config	write	修改该提示词。
delete_attack_surface_agent_config	write	移除该提示词。

suggest_autodiscovery_domains 是这些工具的配套辅助：它将公司的自然语言描述转换为其可能拥有的域名列表，从而为起草配置提示词提供依据，避免从零编写。该工具仅提供建议 — 调用它不会向队列或资产清单添加任何内容。

标签

标签采用 name（名称）与 value（取值）二元组形式，因此相同的名称可以携带不同的取值并存 — 例如 env=prod 与 env=staging 是两个独立的标签。传入 value 可创建带值标签，省略则创建纯文本标签。

工具	权限	说明
list_tags	attack_surface_read	组织中已定义的标签列表，可按名称子字符串过滤。
list_asset_tags	attack_surface_read	当前密钥可访问资产上实际正在使用的标签列表。
add_tag	attack_surface_audit	创建标签，可指定可选颜色、描述与图标。
update_tag	attack_surface_audit	重命名标签或更改其显示样式。
delete_tags	attack_surface_audit	根据 ID 删除指定标签。
delete_unused_tags	attack_surface_audit	删除所有未被任何对象引用的标签。

标签名称专属于特定组织，因此随意猜测的标签名只会匹配不到任何结果，而不会报错。在按标签过滤或附加标签之前，请先调用 list_tags。

update_tag 会在全局范围内更新该标签，所有携带该标签的工单和资产都会同步显示新名称。此工具不能用于将部分项目迁移到其他标签。若尝试将标签重命名为另一现有标签已占用的 name/value 组合，请求将被拒绝，防止未经确认的合并。

delete_tags 会从所有关联的工单和资产中移除该标签。这些工单和资产会被完整保留 — 仅解绑标签关联。该调用遵循“全成功或全失败”原则：若传入的 ID 列表中包含任何未知或无权访问的 ID，则不会执行任何删除，并在错误信息中列出问题 ID。

list_tags 返回组织中定义的所有标签，包含未被任何对象引用的闲置标签。list_asset_tags 仅返回当前密钥可访问资产上正在使用的标签，更适合作为构建过滤条件的参考。

delete_unused_tags 无需传入 ID。它会通过单次调用删除所有未被任何工单及资产引用的标签，该操作不可逆。在执行前建议对比 list_tags 与 list_asset_tags，明确将会删除的标签范围。

测试凭据

测试凭据是平台在执行扫描时可用于身份验证的可复用登录凭据。

工具	权限	说明
list_test_credentials	read	已存储的凭据列表，可按类型及非机密字段子字符串过滤。
create_test_credential	write	存储指定支持类型的新凭据。
update_test_credential	write	替换已存储凭据的取值，并保留其原有 ID。
delete_test_credential	write	删除凭据。

已存储的机密密钥绝不会被明文返回。list_test_credentials 仅返回非敏感标识符，并针对每行数据提供 has_secret 布尔标志。

update_test_credential 属于全量替换而非增量合并。所属凭据类型中未显式传入的字段均会被清空，包括 credential_name 标签。对于需要保留的现有取值，必须完整回传。其 credential_type 必须与凭据创建时的原始类型一致。

在轮换凭据取值时，应优先使用 update_test_credential 而非“删除后重新创建”：这可保持凭据 ID 不变，已配置该凭据的扫描任务能够持续正常认证。若直接删除凭据，依赖它的扫描任务将立即出现身份验证失败。

计划扫描

计划规则按周期性节奏自动触发扫描，是保持常规单次扫描之间资产持续安全覆盖的关键机制。

工具	权限	说明
list_schedule_rules	read	组织的计划规则列表，可按是否启用进行过滤。
create_schedule_rule	write	针对一个或多个资产创建具有指定扫描配置文件与执行周期的规则。
update_schedule_rule	write	修改规则的资产列表、配置文件、周期或启用状态。
delete_schedule_rule	write	删除规则。不可逆。

调度周期支持两种模式。将 cadence_type 设置为 cron 时，crontab 需采用标准的五段式 Cron 表达式（例如每天 16:00 为 0 16 * * *）。将 cadence_type 设置为 continuous 时，max_no_scan_duration_seconds 代表该规则下资产两次扫描之间允许的最长间隔秒数。

Warning

新创建的规则默认处于禁用状态，因为启用的规则会自动周期性触发计费扫描。创建时请保持 active 为默认值，使用 list_schedule_rules 核查配置无误后，再显式启用。仅在您明确要求规则立即开始周期扫描时，才在创建时传入 active=True。

在确认规则无误后，通过调用 update_schedule_rule 并传入 active=True 来正式启用规则。这也是在不丢失配置的前提下临时停用规则的方法。delete_schedule_rule 会彻底删除规则；该规则之前已触发执行的扫描记录将被保留。

自动化规则

自动化规则在安全发现项满足特定条件时自动执行指定操作。自动开单和告警通知路由均基于此机制实现。

工具	权限	说明
list_automation_rules	read	组织的共享规则列表，可按上下文及是否启用进行过滤。
list_action_definitions	read	规则可执行的操作定义，以及各操作所期望的参数列表。
update_automation_rule	write	修改规则的名称、条件、操作、上下文或共享范围，或将其停用。
delete_automation_rule	write	删除规则。
create_automation_rule	admin	根据指定上下文、过滤查询与单项操作创建新规则。

context 的取值必须为 attack_surface、remediation 或 inventory 之一。filter_query 为条件语句，以 JSON 数组形式表示，且必须包含至少一个有效过滤项 — 空数组代表无过滤条件，会导致规则匹配对应上下文下的所有数据行。

与计划规则相同，新建的自动化规则默认处于禁用状态。请先核对条件与操作，再通过 update_automation_rule 进行启用。

如需临时停用规则并保留配置，可调用 update_automation_rule 并传入 active=False，该操作可随时恢复。delete_automation_rule 则为不可逆的彻底删除。

API 密钥仅能查看与整个组织共享的公共规则；个人用户保留为私有的规则不会返回。

规则触发的操作必须是平台预定义的操作。在调用 create_automation_rule 之前，请先调用 list_action_definitions 查询可用操作及其参数要求，避免盲目猜测操作名称导致报错。

扫描器

扫描器部署在您自有的网络环境中用于执行扫描，使得扫描流量直接从您的企业内网发出，而非来自 Ostorlab 云端。扫描器组可聚合多台扫描器，从而允许将扫描任务分配给组而非单台机器。

工具	权限	说明
list_scanners	read	组织可使用的扫描器列表。
list_scanner_groups	read	组织中定义的扫描器组列表。
create_scanner	admin	注册扫描器，以便将扫描绑定到该扫描器。
update_scanner	admin	修改扫描器的名称、描述或所属成员组成员身份。
delete_scanner	admin	注销并停用扫描器。不可逆。
create_scanner_group	admin	创建扫描器组。
update_scanner_group	admin	修改扫描器组的名称、描述或成员扫描器列表。
delete_scanner_group	admin	删除扫描器组。
grant_scanner_access	admin	允许子组织在您拥有的某台扫描器上运行扫描。
revoke_scanner_access	admin	收回对子组织的扫描器访问权限。

grant_scanner_access 与 revoke_scanner_access 仅能操作归属于当前组织下级的子组织，且目标扫描器必须由当前组织直接拥有。授权操作遵循全成功或全失败规则：若传入列表包含非当前组织子组织的实体，整个请求会在执行任何写入之前被整体拒绝。

集成

工具	权限	说明
list_integrations	read	组织已连接的第三方集成列表，包含其启用状态与非机密配置目标。
get_jira_ticket_map	read	查询工单是否已推送到 Jira，以及其对应的 Jira Issue 编号。
configure_jira_integration	write	设置或替换 Jira 工作区 URL、凭据及默认项目。
configure_slack_integration	write	添加 Slack Webhook 并选择在其上通知的扫描完成事件。
create_servicenow_ticket	write	将单个工单作为 Incident 事件推送到 ServiceNow。
get_slack_integration	admin	读取已配置的 Slack Webhook 及其通知开关。
delete_git_pat_integration	admin	删除 Git 个人访问令牌（PAT）集成。
delete_servicenow_sync_config	admin	删除 ServiceNow 同步配置。

在执行任何依赖集成的操作之前（推送工单、发送通知或在回答中引用第三方服务商），请先调用 list_integrations。它会明确列出当前已连接的集成服务商，避免盲目尝试操作导致失败。需要注意的是，显示为启用的集成可能凭据已过期或被撤销；此类工具无法保证该集成当前链路绝对可用。

这些工具绝不会返回敏感凭据，包括 Jira API 令牌、OAuth 密钥、密码以及 Slack Webhook URL，仅返回白名单内的非敏感字段。

两类配置工具在重复调用时的表现有所不同：Jira 在每个组织中仅允许存在一份配置，再次调用 configure_jira_integration 将直接更新该行记录并替换旧凭据；Slack 则支持多配置，再次调用 configure_slack_integration 将新增一个 Webhook，而不是修改现有的。

Warning

delete_git_pat_integration 会导致依赖该凭据的源代码扫描和自动修复 Pull Request 任务中断。存储在 Ostorlab 上的令牌将被删除，但该令牌在第三方 Git 服务商处依然有效，请务必单独前往服务商处撤销该令牌。

delete_servicenow_sync_config 还会销毁该配置下已推送工单的历史记录。ServiceNow 端创建的 Incident 记录仍会保留，但 Ostorlab 工单与其 Incident 编号之间的双向映射关系将丢失，导致已推送工单无法继续追踪或同步更新。若删除了最后一个启用的同步配置，工单将彻底无法送达 ServiceNow。

上表为简要概述。下文各节详细介绍了各服务商的专属工具：后续表格中的内容为该列表的补充扩展，而非重复。

Webhooks

Webhook 集成用于指定接收 Ostorlab 事件推送通知的自有服务 URL。

工具	权限	说明
create_webhook_integration	admin	设置 Ostorlab 发送事件通知的目标位置。
update_webhook_integration	admin	修改 Webhook 的端点 URL、自定义请求头或启用状态。
delete_webhook_integration	admin	删除 Webhook 集成。

Slack

工具	权限	说明
update_slack_integration	admin	修改指定 Slack Webhook 的 URL 或其通知事件开关。
delete_slack_integration	admin	删除指定 Slack Webhook。

由于 configure_slack_integration 采用追加模式而非替换模式，修改现有 Webhook 请使用 update_slack_integration。修改与删除工具均接收 Webhook ID，该 ID 可通过调用 get_slack_integration 获取。

Jira

工具	权限	说明
get_jira_integration	admin	获取已存储的 Jira 配置详情（不含凭据）。
test_jira_integration	admin	执行 Jira 连通性专项检查并按名称逐项报告结果。
create_jira_ticket_map	write	记录工单与外部已存在的 Jira Issue 之间的映射关系。
update_jira_ticket_map	write	将工单的 Jira 映射重定向至另一个 Issue。
delete_jira_ticket_map	write	解除工单与其对应 Jira Issue 的映射关联。
create_jira_ticket	write	为工单在 Jira 中创建全新 Issue 并同步建立映射关系。
list_jira_metadata	admin	查询已存储凭据可见的项目列表、问题类型（Issue Types）与字段列表。

工单映射（Ticket Map）代表单个 Ostorlab 工单与单个 Jira Issue 之间的双向关联链路，可通过 get_jira_ticket_map 读取。三项映射写入工具专门用于手工维护在 Ostorlab 外部直接创建的 Jira Issue 映射。这些工具仅操作映射关系，绝不会创建、编辑或删除 Jira 端的 Issue，因此解除映射后 Jira 端的 Issue 依然完好。

create_jira_ticket 是真正与 Jira API 交互创建实体的工具。它会为工单在 Jira 中创建新 Issue 并一并建立映射记录，适用于 Jira 侧尚未创建该 Issue 的场景。若创建失败，不会留下任何残留数据（无 Issue 且无映射），并会明确报告具体错误原因，例如凭据无权访问指定项目等。

list_jira_metadata 用于获取 create_jira_ticket 和 configure_jira_integration 所需的基础元数据：当前凭据可访问的项目、各项目支持的问题类型，以及可用于映射的字段列表。若结果为空，说明该凭据看不到任何项目，建议先运行 test_jira_integration 进行排查，切勿盲目归咎于工具故障。

test_jira_integration 按项目名称分类输出诊断报告，在失败时能精准指出是 URL、认证凭据还是项目配置存在问题。

Linear

工具	权限	说明
configure_linear_integration	admin	设置或替换 Linear 连接配置。
get_linear_integration	admin	获取已存储的 Linear 配置详情（不含凭据）。
test_linear_integration	admin	检测并报告 Linear 是否已配置、启用且连通。
list_linear_teams	admin	查询可用于创建 Issue 的 Linear 团队列表。

ServiceNow

工具	权限	说明
configure_servicenow_integration	admin	设置或替换 ServiceNow 连接配置。
test_servicenow_integration	admin	运行 ServiceNow 配置的各项检查并按名称逐项报告结果。
delete_servicenow_integration	admin	删除 ServiceNow 集成。
configure_servicenow_sync_config	admin	将工单字段映射至 ServiceNow 数据表及其列。
get_servicenow_sync_config	read	获取同步配置将工单映射到数据表的具体规则。
list_servicenow_fields	read	查询同步配置所针对的 ServiceNow 数据表的列字段。
get_servicenow_ticket_map	read	查询工单是否已推送到 ServiceNow，以及对应的具体记录。
create_servicenow_ticket_map	write	记录工单与外部已存在的 ServiceNow 记录之间的映射关系。
update_servicenow_ticket_map	write	将工单的 ServiceNow 映射重定向至另一条记录。
delete_servicenow_ticket_map	write	解除工单与其对应 ServiceNow 记录的映射关联。

ServiceNow 的配置分为两个步骤：首先调用 configure_servicenow_integration 存储实例地址与认证凭据；随后调用 configure_servicenow_sync_config 指定工单写入的数据表及各工单字段对应的列。建议先调用 list_servicenow_fields 查询目标数据表的实际列定义，确保映射配置准确匹配真实字段。

工单映射工具的工作机制与 Jira 映射一致：仅维护 Ostorlab 工单与 ServiceNow 记录之间的关联链路，绝不改动 ServiceNow 记录本身。create_servicenow_ticket 则是真正用于在 ServiceNow 端创建新记录的工具。

源代码

工具	权限	说明
list_repositories	read	查询 Ostorlab 当前可访问的代码仓库列表。
create_git_pat_integration	admin	注册 Git 个人访问令牌（PAT）。
update_git_pat_integration	admin	替换已存储的令牌或修改其覆盖范围。
create_standard_git_integration	admin	注册自建 Git 实例。
update_standard_git_integration	admin	修改自建 Git 实例注册信息。
delete_standard_git_integration	admin	删除自建 Git 实例注册信息。
enable_github_app_connection	admin	恢复针对 GitHub App 代码仓库的源代码扫描与 Pull Request。
disable_github_app_connection	admin	暂停针对 GitHub App 代码仓库的操作，保留安装配置。
delete_github_app_connection	admin	从组织中彻底移除 GitHub App 安装。
update_source_code_oauth_integration	admin	启用或停用源代码 OAuth 集成。
delete_source_code_oauth_integration	admin	删除源代码 OAuth 集成。

在调用 create_source_code_scan 之前，应先调用 list_repositories。它会列出当前已连接源代码集成所暴露的代码仓库，确保所扫描的目标切实可被平台拉取克隆，避免因猜测名称导致失败。

disable_github_app_connection 是 delete_github_app_connection 的可逆替代方案。禁用操作会暂停扫描和 Pull Request，但保留 GitHub 侧的应用安装，后续可通过 enable_github_app_connection 快速恢复。若执行删除，则会彻底移除安装，重新接入需在 GitHub 侧完整重新执行 App 安装流程。

App Center

工具	权限	说明
create_app_center_integration	admin	连接 App Center 应用程序以自动扫描其最新构建版本。
update_app_center_integration	admin	修改 App Center 集成配置。
delete_app_center_integration	admin	删除 App Center 集成。

Vanta

工具	权限	说明
get_vanta_auth_url	admin	获取在浏览器中打开以授权 Ostorlab 访问 Vanta 的链接。
delete_vanta_integration	write	断开与 Vanta 的连接。

连接 Vanta 必须借助浏览器完成。get_vanta_auth_url 返回一个需由人工在浏览器中打开以进行授权的链接，整个连接流程在浏览器端完成，无法仅凭客户端工具自主闭环。

组织与访问控制

工具	权限	说明
me	无特殊要求（有效密钥即可）	获取当前密钥归属的组织及所携带的角色信息。
list_shared_access_tokens	read	组织的有效共享链接列表，包含每个链接授予的扫描及调用频次。
list_invitations	read	已受邀加入组织但尚未正式加入的人员列表。
create_shared_access_token	write	创建允许无账户人员只读查看单个扫描的共享链接。
revoke_shared_access_token	write	立即注销并失效指定共享链接。
list_organisation_users	admin	拥有组织访问权限的用户列表，包含其角色及限定的所有者作用域。
add_user	admin	邀请人员以指定角色加入组织。
update_user_access	admin	修改成员的角色或其限定的所有者作用域。
revoke_user	admin	撤销人员对组织的访问权限。
review_invitation	admin	批准或拒绝待处理的成员邀请。
get_organisation_settings	admin	获取组织的全局设置与套餐授权配额。
update_organisation_settings	admin	修改可配置的组织设置项。
list_api_keys	admin	组织的 API 密钥列表：名称、角色、创建与过期时间、吊销状态及掩码密钥。
update_api_key	admin	收紧密钥权限：降低角色、移除所有者授权、提前过期时间或重命名。
revoke_api_key	admin	立即彻底吊销 API 密钥。
list_audit_actions	admin	审计日志：记录操作人、操作内容与时间，可按时间范围与执行者过滤。

me 用于描述当前密钥本身，而非自然人。由于服务器以 API 密钥为鉴权主体，对于“我是谁”的回答，是该密钥归属的组织，以及密钥自身的名称、前缀、角色、所有者授权和有效期，不返回任何个人用户账户信息。

add_user 的实质是发送邀请通知，而非直接创建账户。被邀请人会先出现在 list_invitations 中，只有在其接受邀请后，才会出现在 list_organisation_users 列表中。

update_api_key 仅支持权限向下收紧。所设置的角色不得高于密钥当前的现有角色，所有者授权只能缩减不能新增，过期时间只能提前不能延后。因此，该工具无法用于越权提权，且绝不会返回密钥明文。

吊销操作是使 API 密钥彻底失效的唯一机制。仅凭设置过期时间无法使其失效 — 密钥在 MCP 路径上仍可继续鉴权，直到显式标记为 revoked。revoke_api_key 会打上吊销标记，且该操作不可逆。密钥无法自我吊销；此类调用会被直接拒绝，以防止在会话中途中断自身的连接通道。

任何工具均绝不返回 API 密钥的明文内容。明文仅在密钥生成的瞬间出现一次，系统后续仅保存其不可逆哈希。list_api_keys 会返回 masked_key — 即密钥前缀后附带星号掩码的形式，与 Web 应用及审计跟踪中展示的形式保持一致。如需向人工沟通指代具体密钥，请使用此掩码形式。

Warning

任何持有共享访问令牌的人员均可在无账户状态下查看目标扫描及其所有发现项。此类令牌永不过期。list_shared_access_tokens 仅列出当前处于激活状态的共享，每一行都代表某人当前拥有的实际访问权限。原始令牌明文仅在 create_shared_access_token 的响应中返回一次。

当组织停用了操作审计功能时，list_audit_actions 会返回一个空列表而非报错。响应中会包含一个明确说明此情况的 message 字段，以避免将“零记录”误判为“未发生任何操作”。

单点登录

工具	权限	说明
get_saml_config	admin	获取组织的 SAML 单点登录配置。
configure_saml	admin	初始化创建 SAML 单点登录配置。
update_saml	admin	修改现有的 SAML 配置。

configure_saml 属于严格的新建操作：若组织已存在 SAML 配置，调用将被直接拒绝，绝不会覆盖现有配置。update_saml 则专门用于修改已有配置，采用增量部分更新模式 — 仅修改显式传入的字段。建议先调用 get_saml_config 判断适用哪个工具。

修复 SLO

此处 SLO 代表安全修复时效要求：即特定严重性或优先级的工单允许保持在打开状态的最大天数。

工具	权限	说明
get_slo_config	read	获取组织按严重性和按优先级配置的修复时限（天数）。
update_slo_config	write	修改这些修复时限。

时限取值为 null 表示对该严重性或优先级不设立截止期限。update_slo_config 采用增量更新模式：传入正数值将设定对应时限，传入 null 将清除时限，未传入的字段保持不变。传入未知键将被直接拒绝。

UI 自动化提示词

工具	权限	说明
list_ui_automation_rules	read	查询组织可用的 UI 自动化规则。
create_ui_prompts	write	创建 UI 自动化提示词。
update_ui_prompts	write	修改组织自有的 UI 自动化提示词的代码、名称或描述。
delete_ui_prompts	write	删除组织自有的 UI 自动化提示词。不可逆。

code 参数在每次调用中都会执行完整替换，而 name 和 description 仅在显式传入时才更新。因此，即便仅仅打算重命名提示词，也必须同时回传该提示词现有的 code 内容，否则代码字段会被传入的内容整体覆写。

该调用不遵循“全成功或全失败”原则。可访问的提示词会被成功更新，哪怕列表中其他部分更新失败。响应中会明确列出成功更新的 ID，并针对其余各项说明未更新的原因。

list_ui_automation_rules 同时还会返回非当前组织所有的规则，这些是所有组织均可使用的全局共享规则。只有组织自有的提示词才允许修改或删除，因此在列表中正常可见的规则，仍有可能在调用 update_ui_prompts 和 delete_ui_prompts 时被系统拒绝。

知识库

知识库属于 Ostorlab 官方的基础安全参考数据。它对所有组织通用，而非某一组织的私有视图，因此这些工具返回的数据与您个人的具体扫描任务无关。

工具	权限	说明
list_cves	read	查询 CVE 记录，支持按 ID、严重性或描述文本检索。
list_kb_applications	read	查询 Ostorlab 持续监测新发布 CVE 的公开软件列表。
list_kb_targets	read	查询将 CVE 与其受影响软件版本进行关联的映射记录。
list_app_cards	read	查询 Ostorlab 中可用的共享 App Cards。

list_kb_targets 是前两者的双向关联枢纽：给定一个 CVE，它可以列出受影响的软件版本；给定一个软件名称，它可以列出已针对该软件发布的 CVE 列表。

智能体商店

扫描配置文件由各个检测智能体组装而成。智能体商店即所有可用智能体的公共名录。

工具	权限	说明
search_agents	read	按名称在智能体商店中进行搜索。
get_agent	read	获取单个智能体的详细信息，包含其最新版本接受的参数定义。

search_agents 用于发现检索，get_agent 用于查看详情：先按名称搜索获取智能体的 key，再调用详情接口读取该 key 支持的参数选项。

导出

以下工具各自生成对应格式的数据导出文件并返回下载链接，而非直接返回文件内容。请通过 HTTPS 访问返回的 URL，并在请求头中携带相同的 API 密钥（X-API-Key），工作方式与 generate_scan_report 完全一致。

工具	权限	说明
export_scan	read	导出单个扫描的完整归档。
export_scan_sarif	read	导出单个扫描的 SARIF 格式发现项。
export_vulnerabilities	read	导出单个扫描的 CSV 格式发现项。
export_tickets	read	导出 CSV 格式的修复工单数据。
export_assets	attack_surface_read	导出 CSV 格式的已确认资产清单。
export_potential_nodes	attack_surface_read	导出 CSV 格式的待处理发现候选资产。

两项攻击面数据导出工具需要 attack_surface_read 权限，所有角色均具备该权限。其余四项导出工具需要 read 权限，因此持有 attack_surface_auditor 角色的密钥可以导出资产与发现候选，但无法导出扫描、漏洞或工单。

结果限制

所有列表查询工具均设有返回条数上限。不同工具针对该上限的反馈机制有所不同，主要分为三种处理方式：

部分列表工具返回 游标（cursor）。游标是一个不透明的 Token，用于标记当前返回页面的结束位置。它在 next_cursor 字段中返回。在下次调用时将该值作为 cursor 参数传入，即可获取下一页数据。next_cursor 为 null 代表已到达最后一页。切勿尝试解析或自行构造游标 — 其内部构造属于实现细节，仅对生成它的工具本身具备实际意义。

部分列表工具返回 truncated 布尔标志。它提示后续仍有更多数据，但无法直接翻页获取。此时需通过追加更严格的过滤条件来缩小查询范围。

少数工具两者均不提供。对于这类工具，上限是隐蔽生效的：您只会收到达到上限数量的数据行，且没有任何提示告知后续仍有更多数据存在。

工具	默认值	最大值	更多行的指示方式
list_scans	200	200	next_cursor
list_vulnerabilities	200	200	next_cursor
list_assets	200	200	next_cursor
list_risks	200	200	next_cursor
get_scan_status（状态历史）	50	50	无指示
list_scan_profiles	无限制	无限制	不适用
list_checklists	无限制	无限制	不适用
search_vulnerabilities	200	200	truncated
list_tags	200	200	next_cursor
list_api_keys	200	200	truncated
list_shared_access_tokens	200	200	truncated
list_ticket_agents	100	100	truncated
list_owners	200	200	next_cursor
list_asset_locations	200	200	next_cursor
list_autodiscovery_assets	200	200	next_cursor
list_test_credentials	200	200	next_cursor
list_integrations	200	200	next_cursor
list_audit_actions	200	200	next_cursor
list_organisation_users	200	200	next_cursor
list_schedule_rules	100	100	next_cursor
list_automation_rules	100	100	next_cursor
get_slack_integration	100	100	next_cursor
list_ticket_streams	50	200	next_cursor
list_tickets	50	200	truncated 与 next_cursor
list_comments	50	200	truncated 与 next_cursor

请求超出最大值的数量会被自动截断至最大允许值，而不会报错。若请求传入 0、负数或非数字内容，将被拒绝并提示 Invalid limit.。游标与生成它时所使用的过滤条件紧密绑定，若在不同过滤条件下复用游标，请求将被拒绝并提示 Invalid cursor.，防止静默返回错误的页面数据。

对于没有任何分页指示标记的工具，上限截断就是所能获取的完整结果：例如一个包含 500 条状态记录的扫描，通过 get_scan_status 仅返回 50 条，且无任何标记提示其余 450 条的存在。若统计数量至关重要，请使用过滤条件缩小范围 — 切勿依赖大模型直接对列表返回结果进行清点计数。

删除操作

本页面中所有的 delete_* 和 revoke_* 工具都会永久删除对应数据。这涵盖了 delete_ticket、delete_comment、delete_checklist、delete_checklist_item，以及 delete_asset、delete_owner、delete_asset_location、delete_tags、delete_unused_tags、delete_test_credential、delete_scanner、delete_scanner_group、delete_schedule_rule、delete_automation_rule、delete_ui_prompts、delete_ticket_agent、delete_ticket_stream、各类第三方集成删除工具，以及 revoke_api_key、revoke_shared_access_token 和 revoke_user。

部分工具在存在依赖关系时会主动拒绝执行，而不会级联删除。delete_owner 和 delete_asset_location 在仍有对象依赖它们时拒绝删除；delete_asset 则会完整保留挂载在资产名下的扫描记录与发现项。工具是否级联或保留数据，已在各个工具的专有说明段落中明确标注。

工具向客户端广播注解（annotations）信息。注解是附带在工具列表中的提示信息，用于描述调用该工具会产生的行为特征，方便客户端决定在执行前是否需要向您确认。主要使用三种提示：

• readOnlyHint — 工具仅执行只读查询，不改变任何状态。
• destructiveHint — 工具会以不可逆的方式更改系统状态。
• idempotentHint — 重复调用两次该工具与调用一次的效果完全一致。

上述所有涉及删除或覆写数据的工具均被打上了破坏性操作提示（destructiveHint）。

Warning

注解仅属于提示建议，不具备强制执行力。客户端是否实际向您弹窗确认取决于客户端自身的实现。部分客户端会在每次调用破坏性工具时都发起确认，部分客户端在确认一次后即自动记住选择，还有部分客户端完全不进行弹窗确认。无论客户端如何处理，服务器都会如实执行请求。在将具备写入权限的密钥提供给大模型之前，请先明确您的客户端如何处理破坏性提示。

并非所有工具都携带注解。对于未携带注解的工具，客户端将回退至 MCP 规范的默认设定，即假定该调用属于具有破坏性且非幂等的操作。这意味着在谨慎的客户端中，未标注注解的只读工具可能会显得比实际更危险。

错误处理

发生故障的工具仍会返回正常的 HTTP 200 / JSON-RPC 成功响应体，但在其 Body 中会包含一个 error 字段：

{"error": "Invalid API Key."}

此时 JSON-RPC 协议层面的 isError 标志依然保持为 false。若您的客户端代码通过检查 isError 来进行逻辑分支判断，则会将身份验证失败和权限不足错误误判为成功 — 请务必改为检查响应体中的 error 字段。

使用示例

在客户端成功连接服务器后，以下是一些推荐的有效提示词示例：

• “列出上周完成且风险评级为高（high）的扫描。”
• “显示扫描 12345 中的严重漏洞，并为每个漏洞创建一个工单。”
• “漏洞 987 的技术详情是什么？是否有人在其工单上发表了评论？”
• “将漏洞 654 标记为误报。”
• “哪些处于打开状态的工单已分配给 rubberduck？”
• “我们可以针对 Web 目标运行哪些扫描配置文件？并在 example.com 上启动一次快速扫描（Fast Scan）。”
• “我们的哪些 API 密钥从未被吊销且创建于一年以上之前？”
• “攻击面发现队列中评分高于 80 的资产有哪些？”

故障排除

连接时出现 HTTP 404 错误 URL 缺少了密钥段或末尾缺少斜杠。正确的格式必须严格为： /apis/mcp/YOUR_API_KEY/。

Invalid API Key. 密钥无法解析。请检查密钥是否完整复制，以及该密钥是否已被吊销。

API Key does not have write permission. 该工具所需的角色权限高于当前密钥所持有的角色。请签发具备对应所需角色的新密钥。

在 Web 应用中可见的扫描提示 Scan not found. 常见原因有四种：扫描已被归档（get_scan 和 get_scan_status 会拒绝读取已归档扫描）；扫描属于其他组织；您的组织启用了对象级访问控制，而当前密钥未被授予该扫描的权限；或者该 ID 属于 AI 渗透测试而非扫描 — 扫描类工具无法解析 AI 渗透测试 ID，对此类目标请使用 get_agentic_deep_scan。无法访问的扫描与完全不存在的扫描在返回表现上经过有意设计，保持一致。