apply-universal-policy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apply Universal Policy

应用 Universal Policy

Protect APIs across gateways with one Universal policy: discover what is missing, collect configuration once, apply in one call, and wait until the work has actually finished.
使用一项 Universal 策略保护各网关上的 API:发现缺失项、一次性收集配置、通过一次调用完成应用,并等待工作真正结束。

When to Use This Skill

何时使用此技能

Use this skill when the user asks to:
  • "Ensure all my finance-tagged APIs have JWT validation"
  • Apply one canonical policy (JWT, rate limiting, spike arrest, IP allow/deny) across many instances or many providers
Trigger keywords: all my APIs · portfolio · missing this policy · universal policy · canonical policy · JWT validation · rate limiting · spike arrest.
Do NOT use this skill when:
  • They ask what protection they already have, or want to change an already-applied native policy ("improve IP filtering to include 1.1.1.1") → skill apply-native-policy-to-instance (Audit / Edit)
  • The user already has one instance in context and wants a native plugin on it (Kong / Apigee / Azure / one MuleSoft instance) → skill apply-native-policy-to-instance
  • They are driving Anypoint REST rather than MCP → skill apply-policy-to-api-instance
  • They need to create an instance or deploy a gateway first → skill secure-api
  • They want to remove, detach, or pause (enable/disable) a policy — say so and stop; those actions are not on the tool surface
当用户要求:
  • “确保我所有带 finance 标签的 API 都具备 JWT validation”
  • 跨多个实例或多个提供商应用一项 canonical 策略(JWT、rate limiting、spike arrest、IP allow/deny)
触发关键词: all my APIs · portfolio · missing this policy · universal policy · canonical policy · JWT validation · rate limiting · spike arrest.
不要在以下情况下使用此技能:
  • 用户询问当前有哪些防护,或希望更改已应用的原生策略(“改进 IP filtering,使其包含 1.1.1.1”) → skill apply-native-policy-to-instance(Audit / Edit)
  • 用户的上下文中已经确定了一个实例,并希望在该实例上使用原生插件(Kong / Apigee / Azure / 一个 MuleSoft 实例) → skill apply-native-policy-to-instance
  • 用户使用的是 Anypoint REST 而不是 MCP → skill apply-policy-to-api-instance
  • 用户需要创建实例或先部署网关 → skill secure-api
  • 用户希望移除、分离或暂停(启用/禁用)策略——应说明这一点并停止;工具接口不提供这些操作

Prerequisites

前置条件

You must be connected to the MuleSoft Platform MCP Server (
urn:mcp:mulesoft-platform
). Probe with a read-only call:
  1. Call
    list_universal_policies
    . If the tool is not in the catalog, STOP and say the Platform MCP catalog on this host does not include the Universal policy tools yet. Do not substitute Anypoint REST calls.
  2. If the tool returns the catalog is unavailable (
    status=not_configured
    or an empty
    policies
    list with that message), say so and stop — do not invent a fallback apply path.
  3. On a 403 / entitlement / gate-closed error, say they are not entitled and stop. Never silently switch provider or org.
必须连接到 MuleSoft Platform MCP Server (
urn:mcp:mulesoft-platform
)。使用只读调用进行探测:
  1. 调用
    list_universal_policies
    。如果该工具不在目录中,请停止,并说明此主机上的 Platform MCP 目录尚不包含 Universal 策略工具。不要改用 Anypoint REST 调用。
  2. 如果工具返回目录不可用(
    status=not_configured
    ,或带有该消息的
    policies
    空列表),说明情况并停止——不要虚构回退应用路径。
  3. 遇到 403 / entitlement / gate-closed 错误时,说明用户无权使用并停止。绝不静默切换提供商或组织。

Reference files

参考文件

  • references/presentation-format.md
    — pinned tables. Read it when you are about to render a user-facing list, schema, mapping, or result.
  • references/payloads.md
    — how to join
    find_assets
    rows and branch on apply
    status
    . Read it before the first apply.
  • references/presentation-format.md
    ——固定表格。在准备呈现面向用户的列表、模式、映射或结果时阅读。
  • references/payloads.md
    ——如何关联
    find_assets
    结果行,以及如何根据 apply
    status
    分支处理。首次 apply 前阅读。

Workflow

工作流

Pick the path first

先选择路径

This skill is Protect only. If the latest turn is "what's applied" or "change this native policy", switch to skill apply-native-policy-to-instance — do not run Steps 1–4.
此技能仅用于 Protect。如果最新一轮对话是“已应用了什么”或“更改这项原生策略”,请切换到 skill apply-native-policy-to-instance——不要执行步骤 1–4。

Rules that always apply

始终适用的规则

  1. Confirm before acting. Report found/missing and wait for an explicit yes before
    apply_universal_policy
    . A missing confirmation writes policies the user did not approve.
  2. Instances, not APIs. Users say "APIs"; policies attach to deployed instances. Gate apply on
    policyCoverage
    +
    instancesMissingPolicy
    , never on
    hasPolicy
    alone (
    hasPolicy
    is any-instance and would skip unprotected siblings).
  3. Join before you talk.
    instancesMissingPolicy
    is
    {instanceId, environment}
    only. Build display rows and
    instance_ids
    using
    references/payloads.md
    — do not invent names or providers.
  4. Apply: one config, one shot. Show the schema table (full surface, or required-only when it is too long — see
    references/presentation-format.md
    ), then collect the entire configuration for the fields you showed in one reply. Reuse it across every targeted instance. Never walk field by field.
  5. Wait for completion. Acceptance (
    accepted
    / HTTP 202) is not success. Poll until
    COMPLETED
    or
    FAILED
    . Distinguish retryable vs terminal from
    error.retryable
    .
  6. Plain names. Mappings use human-readable native policy names from
    providerMapping
    , not IDs.
  1. 执行前确认。 报告已找到和缺失的内容,并在调用
    apply_universal_policy
    前等待用户明确确认。未获确认就执行会写入用户未批准的策略。
  2. 实例,而非 API。 用户会说“APIs”,但策略附加到已部署的实例。是否允许 apply 应基于
    policyCoverage
    +
    instancesMissingPolicy
    ,绝不能只依赖
    hasPolicy
    (
    hasPolicy
    表示任意实例拥有该策略,会漏掉尚未受保护的同级实例)。
  3. 先关联,再展示。
    instancesMissingPolicy
    仅包含
    {instanceId, environment}
    。使用
    references/payloads.md
    构建展示行和
    instance_ids
    ——不要虚构名称或提供商。
  4. 应用:一次配置,一次执行。 先展示模式表(完整字段范围;如果太长则仅展示必填字段——参见
    references/presentation-format.md
    ),然后在一次回复中收集所展示字段的完整配置。在每个目标实例上原样复用。绝不逐个字段询问。
  5. 等待完成。 接受(
    accepted
    / HTTP 202)并不等于成功。持续轮询,直到
    COMPLETED
    或
    FAILED
    。根据
    error.retryable
    区分可重试状态与终止状态。
  6. 使用直观名称。 映射使用来自
    providerMapping
    的可读原生策略名称,而不是 ID。

Step 1: Discover the slice and what's missing (Protect)

步骤 1:发现目标切片及缺失项(Protect)

Call
find_assets
with:
  • query
    — search terms from the request (names, "finance", "payments"). Include tag-like words when the user said "tagged", but do not claim a tag filter the backend did not apply — if hits look unrelated, say you searched by those terms.
  • asset_type
    —
    api
    when they mean APIs (expands to the API Exchange types)
  • user_query
    — the verbatim user message
  • include_applied_policies
    —
    true
  • policy_name_filter
    — the protection they named ("JWT validation", "rate-limiting"; matching is case- and separator-insensitive)
  • max_results
    — raise it when they asked for "all" / a large slice (default is 20)
If
userOrgAssets
is empty, say you found no matching API instances and stop. Do not search the public catalog for apply targets.
Present the API-instance list (
references/presentation-format.md
) using the join in
references/payloads.md
. Summarize per instance: "N instances found, M missing this policy, K unknown."
Coverage rules:
policyCoverage
MeaningApply to
all
Every readable instance has itskip (already protected)
partial
/
none
Some or none have itexactly the joined
instancesMissingPolicy
unknown
Incomplete read (error or cap)re-check with
view_api_instance_policies
. Never count as missing.
If
appliedPolicyEnrichment.assetCapApplied
is true, fan out
view_api_instance_policies
for the remaining instances rather than treating the truncated set as complete.
[GATE] Wait for the user to confirm they want you to fix the gap.
使用以下参数调用
find_assets
:
  • query
    ——来自请求的搜索词(名称、“finance”、“payments”)。当用户提到“tagged”时加入类似标签的词,但不要声称后端应用了标签过滤——如果命中结果看起来不相关,应说明你是按这些词搜索的。
  • asset_type
    ——当用户指 API 时设为
    api
    (会扩展到 API Exchange 类型)
  • user_query
    ——用户消息的原文
  • include_applied_policies
    ——
    true
  • policy_name_filter
    ——用户指定的防护(“JWT validation”、“rate-limiting”;匹配时不区分大小写和分隔符)
  • max_results
    ——当用户要求“全部”或较大切片时提高此值(默认值为 20)
如果
userOrgAssets
为空,说明未找到匹配的 API 实例并停止。不要在公共目录中搜索应用目标。
使用
references/payloads.md
中的关联方式,按照
references/presentation-format.md
展示 API 实例列表。按实例汇总: “找到 N 个实例,其中 M 个缺少此策略,K 个状态未知。”
覆盖规则:
policyCoverage
含义应用对象
all
每个可读实例都有该策略跳过(已受保护)
partial
/
none
部分或全部实例缺少该策略仅应用于关联得到的
instancesMissingPolicy
unknown
读取不完整(错误或达到上限)使用
view_api_instance_policies
重新检查。绝不能计为缺失。
如果
appliedPolicyEnrichment.assetCapApplied
为 true,应对其余实例批量调用
view_api_instance_policies
,而不是将截断后的集合视为完整集合。
[GATE] 等待用户确认是否需要修复这些缺口。

Step 2: Choose the Universal policy and show its schema (Protect)

步骤 2:选择 Universal 策略并展示其模式(Protect)

Call
list_universal_policies
with
policy_name_hint
from the user's protection. If more than one template matches, list their
label
s and ask which to use — do not pick silently.
Each entry has
configurationSchema
,
supportedProviders
, and
providerMapping
(what it becomes on Kong / Apigee / …).
Drop any target instance whose provider is not in
supportedProviders
. If that leaves none, say so and stop. Keep the surviving list — that is the apply set for Steps 3–4, not the raw Step 1 missing list.
Present the policy configuration schema table (
references/presentation-format.md
). If the flattened schema is too long to scan, show required fields only, say how many optionals are hidden, and offer to expand. Then ask the user to fill the visible fields in one reply. Do not invent optional values; omitted hidden fields keep schema defaults.
使用与用户所需防护对应的
policy_name_hint
调用
list_universal_policies
。如果匹配到多个模板,列出它们的
label
并询问用户选择哪一个——不要擅自选择。
每个条目都包含
configurationSchema
、
supportedProviders
和
providerMapping
(该策略在 Kong / Apigee / 等平台上对应的形式)。
移除任何提供商不在
supportedProviders
中的目标实例。如果过滤后没有实例,说明情况并停止。保留剩余列表——它是步骤 3–4 的应用集合,而不是步骤 1 的原始缺失列表。
按照
references/presentation-format.md
展示 策略配置模式表。如果扁平化后的模式过长,难以快速浏览,则仅展示必填字段,说明隐藏了多少个可选字段,并询问是否需要展开。然后要求用户一次性填写回复中展示的所有可见字段。不要虚构可选值;省略的隐藏字段将保留模式默认值。

Step 3: Preview the native mapping, then apply (Protect)

步骤 3:预览原生映射,然后应用(Protect)

Build the policy → API + instance mapping by joining each remaining instance's provider to
providerMapping
. Show it. [GATE] Wait for okay.
Call
apply_universal_policy
once with:
  • policy_name
    — the canonical kebab-case template
    name
  • instance_ids
    — remaining missing instances from Step 2 (after the provider drop), not the raw Step 1 list
  • configuration
    — the collected config, reused as-is
Do not loop
apply_policy_to_instance
for a Universal/canonical template. That tool is one native plugin on one instance — skill apply-native-policy-to-instance.
将每个剩余实例的提供商与
providerMapping
关联,构建策略 → API + 实例映射。展示该映射。[GATE] 等待用户确认。
调用一次
apply_universal_policy
,参数如下:
  • policy_name
    ——canonical kebab-case 模板的
    name
  • instance_ids
    ——步骤 2 中经过提供商过滤后剩余的缺失实例,而不是步骤 1 的原始列表
  • configuration
    ——收集到的配置,并原样复用
对于 Universal/canonical 模板,不要循环调用
apply_policy_to_instance
。该工具用于在一个实例上应用一个原生插件——应使用 skill apply-native-policy-to-instance。

Step 4: Wait until it is actually done (Protect)

步骤 4:等待实际完成(Protect)

Branch on the apply
status
(
references/payloads.md
):
  • accepted
    — poll
    get_policy_operation_status
    with
    operationId
    until
    COMPLETED
    or
    FAILED
    (not
    RUNNING
    ). A few seconds between polls; give up after ~20 attempts and report Still running.
  • ok
    — synchronous success. Report immediately. Do not poll.
  • partial
    — some targets failed. Report Partially succeeded from
    results
    . Do not poll.
Then the same policy → API + instance mapping as the preview (now as the result). On
FAILED
, say whether
error.retryable
is true.
根据 apply
status
分支处理(
references/payloads.md
):
  • accepted
    ——使用
    operationId
    调用
    get_policy_operation_status
    轮询,直到
    COMPLETED
    或
    FAILED
    (不能停在
    RUNNING
    )。每次轮询间隔几秒;约尝试 20 次后放弃,并报告 Still running。
  • ok
    ——同步成功。立即报告。不要轮询。
  • partial
    ——部分目标失败。根据
    results
    报告 Partially succeeded。不要轮询。
然后展示与预览阶段相同的策略 → API + 实例映射,作为最终结果。在
FAILED
时,说明
error.retryable
是否为 true。

Best Practices

最佳实践

  • Route first. ✅ "what's applied" / "change IP filtering" goes to skill apply-native-policy-to-instance. ❌ running Step 1's
    policy_name_filter
    + apply GATE on an audit turn.
  • One apply call for Universal. ✅
    apply_universal_policy
    with the Step-2 remaining ids. ❌ looping native apply; ❌ sending the pre-drop Step 1 list.
  • Don't invent display fields. ✅ join
    instanceId
    as in
    references/payloads.md
    . ❌ filling provider/name from memory.
  • 先路由。 ✅ “已应用了什么” / “更改 IP filtering”转到 skill apply-native-policy-to-instance。❌ 在审计轮次中执行步骤 1 的
    policy_name_filter
    + apply GATE。
  • Universal 使用一次 apply 调用。 ✅ 使用步骤 2 的剩余 ID 调用
    apply_universal_policy
    。❌ 循环执行原生 apply;❌ 发送步骤 1 中尚未经过提供商过滤的列表。
  • 不要虚构展示字段。 ✅ 按照
    references/payloads.md
    关联
    instanceId
    。❌ 根据记忆填写提供商或名称。

Troubleshooting

故障排除

Universal policy tools are missing from the catalog: say so and stop. Do not substitute Anypoint REST calls.
policyCoverage
is
unknown
, or the table shows
?
:
re-read those instances with
view_api_instance_policies
. Do not apply as if they were missing.
403 / not entitled / gate closed: the org cannot manage that provider's policies. Say so plainly and stop.
Apply returned
ok
or
partial
and you started polling:
those statuses are already terminal. Report from
results
; only
accepted
has an
operationId
to poll.
User asks to undo / remove / disable the policy: not supported. There is no detach tool and no enable/disable parameter on the agent surface. Explain and stop.
Universal 策略工具不在目录中: 说明情况并停止。不要改用 Anypoint REST 调用。
policyCoverage
为
unknown
,或表格显示
?
:
使用
view_api_instance_policies
重新读取这些实例。不要将它们视为缺失并直接应用。
403 / 无权限 / gate closed: 该组织无法管理对应提供商的策略。直截了当地说明情况并停止。
Apply 返回
ok
或
partial
,但你开始轮询:
这些状态已经是终态。根据
results
进行报告;只有
accepted
状态包含可供轮询的
operationId
。
用户要求撤销 / 移除 / 禁用策略: 不支持。Agent 接口面上没有 detach 工具,也没有 enable/disable 参数。进行解释并停止。

Related Skills

相关技能

  • skill apply-native-policy-to-instance: list what's applied, edit an already-applied native policy, or apply one native plugin/template to one instance (Kong / Apigee / Azure / MuleSoft) via MCP.
  • skill apply-policy-to-api-instance: same single-instance job over Anypoint REST (
    urn:api:*
    ), not MCP.
  • skill secure-api: create/deploy an instance and then apply a policy — use that when the API is not yet an instance.
  • skill secure-mcp-server: protect an MCP server, not an API instance.
  • skill apply-native-policy-to-instance:通过 MCP 列出已应用的策略、编辑已应用的原生策略,或在一个实例(Kong / Apigee / Azure / MuleSoft)上应用一个原生插件或模板。
  • skill apply-policy-to-api-instance:通过 Anypoint REST(
    urn:api:*
    )而非 MCP 执行相同的单实例任务。
  • skill secure-api:创建或部署实例,然后应用策略——当 API 尚不是实例时使用。
  • skill secure-mcp-server:保护 MCP Server,而非 API 实例。