Toolsets

The Zscaler MCP server groups its 280+ tools into toolsets — small, named bundles of related tools. Toolsets let you load only the slice of tools an agent actually needs, instead of every tool the server can expose.

Applies to every transport. Toolsets, the toolset selection flags, the runtime discovery tools, and the OneAPI entitlement filter described on this page work identically on stdio, sse, and streamable-http. They are tool-level controls, not transport-level controls.

Why toolsets exist

Smaller agent context. Loading every tool into a model's prompt is expensive and confuses tool selection. Selecting two toolsets (~15 tools) instead of every tool (~280) materially improves the agent's accuracy and speeds responses.
Per-toolset guidance. Each toolset can contribute a short paragraph of system instructions, sent to the agent only when the matching tools are loaded — so guidance about (for example) Cloud App Control rule semantics arrives only when those tools are active.
Dynamic discovery. Three always-on tools let the agent enumerate the available toolsets and turn additional ones on at runtime when the user asks for a capability that wasn't loaded.

Quick reference

What you want	How
Run with everything (today's default)	No `--toolsets` flag.
Run with the curated default-on subset	`--toolsets default`
Run with everything explicitly	`--toolsets all`
Run with a narrow custom set	`--toolsets zia_url_filtering,zpa_app_segments`
Set via environment variable	`ZSCALER_MCP_TOOLSETS=zia_url_filtering,zpa_app_segments`
Discover what exists	Call `zscaler_list_toolsets` from your client.
Inspect a toolset	Call `zscaler_get_toolset_tools` with a toolset id.
Enable more at runtime	Call `zscaler_enable_toolset` with a toolset id.
Skip the entitlement filter	`--no-entitlement-filter` or `ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER=true`

The meta toolset (containing the connectivity check, service discovery, tool search, and the three discovery tools above) is always loaded and cannot be filtered out.

Toolset catalog

Every registered toolset, grouped by service. A default-on toolset loads automatically when you start the server without --toolsets. An opt-in toolset only loads when you explicitly ask for it (or run with --toolsets all). The meta toolset is always on — it can't be filtered out because the agent needs it for runtime discovery.

The catalog is generated from zscaler_mcp/common/toolsets.py by make generate-docs. CI fails the build if the live inventory drifts from the rendered page.

53 toolsets387 tools10 services

METAcross-service1 toolset

How selection resolves

The selection pipeline is deterministic:

No --toolsets flag → every toolset whose service is enabled is selected (today's behaviour, no breaking change).
--toolsets default → every toolset marked default-on in the catalog above.
--toolsets all → every registered toolset.
--toolsets a,b,default → explicit ids a and b plus the default expansion.
--toolsets a,unknown → a is loaded; unknown produces a startup WARNING listing the valid ids.

The meta toolset is always force-added. Tools belonging to the meta toolset bypass the toolset filter entirely.

Filter precedence

Once toolsets are selected, every tool that comes up for registration is checked against four filters in this order:

--disabled-tools (fnmatch patterns) — wins absolutely. A disabled tool stays disabled even if it's in an active toolset and even if it's a write tool you allowlisted.
Toolset filter — the tool must belong to an active toolset (or be a meta tool).
--enabled-tools — explicit name allowlist when set; if unset, every tool that survived the previous step is registered.
Write tools only: the tool must additionally pass --enable-write-tools AND match a pattern in --write-tools. With write tools disabled (the default), no *_create_* / *_update_* / *_delete_* tool is ever exposed regardless of the other filters.

Concrete examples:

Invocation	Result
`--toolsets zia_url_filtering`	5 read tools (list, get, list_lite). No writes.
`--toolsets zia_url_filtering --enable-write-tools --write-tools 'zia_*'`	All 8 tools (5 read + 3 write).
`--toolsets all --disabled-tools 'zcc_*'`	Every tool except ZCC.
`--toolsets zia_url_filtering --disabled-tools 'zia_url_filtering'`	0 tools (exclusion wins).

OneAPI entitlement filter

After your --toolsets selection is resolved, the server applies one more pass: it looks at the OneAPI bearer token issued for your ZSCALER_CLIENT_ID and trims the selection down to the products that token is actually entitled to call.

In other words: if your OneAPI client is only entitled to ZIA and ZPA, every zdx_* / zcc_* / ztw_* / zid_* / zeasm_* / zins_* / zms_* toolset is silently dropped before tool registration runs — even if you asked for --toolsets all. This prevents an agent from discovering tools whose first call would only ever return 401 Unauthorized.

The filter applies on every transport, including stdio. It runs once at server startup, before any tool is registered.

What gets checked

Only product entitlement is honoured — the list of Zscaler products (ZIA, ZPA, ZDX, ZCC, ZTW, ZIdentity, External ASM, Z-Insights, Microsegmentation) your API client has been granted access to in ZIdentity.

The filter intentionally does not look at role names. Roles in the Zscaler console are free-form admin labels and the permissions inside them are evaluated server-side at the API. Filtering by role name in the MCP server would either be too strict (block calls that would have succeeded) or too loose (advertise tools that the role can't actually execute). The MCP server defers all per-action permission enforcement to the live API; the entitlement filter only ensures we don't advertise tools for products the client has zero access to.

What you'll see at startup

When the filter runs successfully you'll see an INFO line like:

entitlement filter applied: entitled services=['zia', 'zpa'], kept 12 toolset(s), removed 17 toolset(s)

When the filter is skipped (any failure path — see below) you'll see a single WARN line explaining why, and the server starts normally with the user-selected toolsets unchanged.

When the filter is skipped

The filter is non-fatal by design. Any of the following result in a single WARN log line and the filter being bypassed:

OneAPI credentials are missing.
The ZIdentity token endpoint is unreachable, returns a non-200 status, or times out.
The token isn't a parseable JWT.
The token has no recognizable product entitlements.

In every one of these cases the server still starts. You just don't get the entitlement-driven trim.

Disabling the filter

Use either of these escape hatches if you ever need to bypass the filter (for example, while diagnosing an unusual token shape):

CLI: --no-entitlement-filter
Env: ZSCALER_MCP_DISABLE_ENTITLEMENT_FILTER=true

Either one short-circuits the filter entirely; your --toolsets selection is used as-is.

Interaction with `--toolsets`

The filter intersects with your selection — it never expands it.

Operator selection	Token entitles	Final loaded toolsets
`--toolsets all`	ZIA, ZPA	every ZIA + ZPA toolset (plus `meta`)
`--toolsets zia_url_filtering,zpa_app_segments`	ZIA only	`zia_url_filtering` (plus `meta`) — ZPA stripped
`--toolsets zia_url_filtering`	ZPA only	`meta` only — you asked for ZIA but the token doesn't entitle it
(no flag)	ZIA, ZPA, ZDX	every toolset for those three products (plus `meta`)
(no flag)	ZIA only	every ZIA toolset (plus `meta`)
`--no-entitlement-filter` + anything	(filter skipped)	exactly what you selected

The meta toolset always survives — it's the agent's only way to discover and re-enable additional toolsets at runtime.

Per-toolset instructions

Toolsets carry an optional short snippet of guidance that is composed into the server's system instructions field at startup, but only when the toolset is in the active selection.

For example, with --toolsets zia_cloud_app_control, the server's instructions field includes:

Cloud App Control rules: rule_type is required on every zia_create/update/delete_cloud_app_control_rule. Discover it via zia_list_cloud_app_policy — the app's parent field is the rule_type. Then call zia_list_cloud_app_control_actions to get the valid actions enum for that category.

With --toolsets zia_url_filtering instead, that snippet is not sent — saving the agent context that would never be useful for URL filtering tasks.

Snippets shared by multiple toolsets (the ZIA rule-family snippet about order/rank/PUT-replace semantics is bound to all five ZIA rule toolsets) are de-duplicated automatically — they appear once even if several of those toolsets are active.

Discovery tools

The agent can introspect and reconfigure the active toolsets at runtime via three tools that are always loaded.

`zscaler_list_toolsets`

Returns every registered toolset with description, default flag, currently-enabled status, and member tool count. This is the agent's first stop when a user asks for a capability that doesn't appear in the loaded tool list.

`zscaler_get_toolset_tools`

Takes a toolset id and returns its member tool names + descriptions. Use this to inspect what enabling a toolset would give you.

`zscaler_enable_toolset`

Takes a toolset id and registers its tools at runtime. After this call the toolset's tools become available for the rest of the session.

> zscaler_enable_toolset(toolset="zia_dlp")
{"toolset": "zia_dlp", "newly_registered": 5, "status": "enabled"}

If the toolset is already enabled, status is already_enabled and newly_registered is 0. Unknown ids return status: "error" with a remediation hint pointing to zscaler_list_toolsets.

Note: Some MCP clients don't emit a list-changed notification for tools added at runtime. Most clients re-list tools on the next request, so the new tools appear naturally.

Deferred to a follow-up

The following are explicitly not part of this version because they require per-request server architecture that the project hasn't shipped yet:

HTTP header overrides (X-MCP-Toolsets, X-MCP-Tools, X-MCP-Exclude-Tools, X-MCP-Readonly) for per-request toolset switching on HTTP transports.
URL-path shortcuts for the same.

Until then, runtime activation through zscaler_enable_toolset covers the same end-user effect from inside the agent session.

For developers — adding a new toolset

This section is for contributors. End users can stop reading here.

In zscaler_mcp/common/toolsets.py, register a new metadata entry:

TOOLSETS.register(ToolsetMetadata(
    id="zia_my_new_area",
    service="zia",
    description="Short human-readable summary.",
    default=False,
    instructions=lambda _catalog: "Optional 1-4 sentence guidance.",
))

Map your tool names to the new toolset, either via an explicit entry in _TOOL_TOOLSET_OVERRIDES (exact match) or a new prefix rule in _TOOLSET_PREFIX_RULES (predicate-based, first-match-wins; list more-specific patterns first).
Run pytest tests/test_toolsets.py::TestToolsetForTool::test_every_registered_tool_resolves — it asserts every tool name in services.py resolves to a registered toolset.
Run make generate-docs to refresh the rendered catalog table (above) and the JSON file consumed by the docs-site ToolsetsCatalog component (docs-site/src/data/toolsets.json). CI runs make check-docs and will fail the build if the catalog renders drift.

Why toolsets exist​

Quick reference​

Toolset catalog​

How selection resolves​

Filter precedence​

OneAPI entitlement filter​

What gets checked​

What you'll see at startup​

When the filter is skipped​

Disabling the filter​

Interaction with --toolsets​

Per-toolset instructions​

Discovery tools​

zscaler_list_toolsets​

zscaler_get_toolset_tools​

zscaler_enable_toolset​

Deferred to a follow-up​

For developers — adding a new toolset​