Microsoft Cloud — Cloud App Discovery Tools

The five Cloud App Discovery tools read Cloud Discovery data from Microsoft Defender for Cloud Apps — the shadow IT picture assembled from Defender for Endpoint telemetry and uploaded firewall or proxy logs. They answer questions like "what cloud apps are actually in use here", "which of them are risky or unsanctioned", and "who is using them" — including generative AI services, AI model providers, and MCP servers, which surface as their own app categories.

Discovery data is organized in streams: expect at least the Global stream, plus a Defender-managed endpoints stream when Defender for Endpoint log streaming is configured. Apps are always queried per stream and per look-back period (P7D, P30D, or P90D — default P30D).

All tools accept an optional connection_id. Omit it to use the default Entra connection. See entra_connection_list for multi-tenant scenarios.

INFO

These tools require the CloudApp-Discovery.Read.All application permission. The current onboarding script grants it; tenants provisioned before it was added must re-run the script or consent manually — see Connecting Entra ID.

WARNING

Traffic counters (upload and download bytes, transaction counts) exist only at the app level. There is no per-user or per-device traffic attribution anywhere in this API — the entity tools return identifiers only.

Streams

mscloud_cloudappdiscovery_list_streams

Lists the uploaded Cloud Discovery streams. Apps are stream-scoped, so this is the entry point — take a stream's id into mscloud_cloudappdiscovery_list_apps. An empty result means no Cloud Discovery data is flowing: Defender for Endpoint integration or log upload is not set up. Takes only an optional connection_id.

Example prompt.

"Which Cloud Discovery streams do we have, and is endpoint data flowing?"

Discovered Apps

mscloud_cloudappdiscovery_list_apps

Lists discovered cloud apps for a stream and period. Each app carries its name, category, domains, risk score, tags (Sanctioned, Unsanctioned, Monitored, or custom), upload and download traffic in bytes, transaction count, user/IP/device counts, and last-seen date.

risk_score_max and category filter server-side; tag and domain are applied client-side by scanning multiple stream pages. That scan is bounded — it inspects up to several hundred apps per call and reports scannedApps so you know how far it reached. When the bound is hit before the stream ends, the response also sets scanTruncated with a nextSkip to continue. Note that risk scores run from 1 to 10 with lower meaning riskier.

Parameter	Type	Required	Description
stream_id	string	✓	Stream ID from mscloud_cloudappdiscovery_list_streams.
connection_id	string	—	Target Entra tenant.
period	string	—	P7D, P30D, or P90D. Default P30D.
risk_score_max	integer	—	Only apps with risk score ≤ this value (1–10, lower = riskier).
category	string	—	One category, e.g. cloudStorage, generativeAi, aiModelProvider, mcpServer, clientAiApp.
tag	string	—	Sanctioned, Unsanctioned, Monitored, or a custom tag (client-side).
domain	string	—	Apps using this domain (client-side exact match).
filter	string	—	Raw OData $filter escape hatch (overrides risk_score_max/category). Supports server-side conditions on riskScore, category, and the catalog compliance/security attributes, e.g. appInfo/isHipaaCompliant eq 'false' and category eq 'marketing' to find non-HIPAA-compliant apps in a category.
select	string	—	Comma-separated property list.
top	number	—	Page size, default 25.
skip	integer	—	Offset paging — pass the previous response's nextSkip.

Example prompt.

"List the riskiest unsanctioned cloud apps seen in the last 30 days."

mscloud_cloudappdiscovery_get_app

Returns full details for a single discovered app: the usage-level detail from the list view plus — by default — the app's catalog risk and compliance attributes: vendor, headquarters, hosting and data center, encryption, latest breach date, and roughly ninety security, legal, and compliance flags (HIPAA, GDPR, SOC, ISO, FedRAMP, MFA, SAML, and more). Attributes valued unknown are dropped to keep the response compact; set include_app_info to false for usage-level data only.

Parameter	Type	Required	Description
stream_id	string	✓	Stream ID.
app_id	string	✓	The id from mscloud_cloudappdiscovery_list_apps.
connection_id	string	—	Target Entra tenant.
period	string	—	Must match the period the app was listed under. Default P30D.
include_app_info	boolean	—	Include the catalog compliance block. Default true.

Example prompt.

"Is this file-sharing app GDPR and SOC 2 compliant, and has the vendor been breached?"

Who Uses What

mscloud_cloudappdiscovery_get_app_entities

Drills down on one app to list the users, devices, or IP addresses that accessed it. Returns identifiers only — there is no per-entity traffic or transaction data. devices is populated only for streams fed by Defender for Endpoint.

Parameter	Type	Required	Description
stream_id	string	✓	Stream ID.
app_id	string	✓	The discovered app ID.
entity_type	string	✓	users, devices, or ips.
connection_id	string	—	Target Entra tenant.
period	string	—	Must match the period the app was listed under.
top	number	—	Page size.
skip	integer	—	Offset paging — pass the previous response's nextSkip.

Example prompt.

"Which users accessed this generative AI app in the last week?"

mscloud_cloudappdiscovery_apps_by_entity

Reverse index: "which discovered apps does user X (or device Y) use?" Built by scanning the app list and inverting each app's drill-down, since no native per-entity endpoint exists. Output per entity is the list of apps it used with each app's app-level risk score, tags, and traffic — the traffic is the app's total, not attributable to the entity.

Each scanned app costs one extra API call, so the scan is bounded by max_apps (default 25, ceiling 100). On large tenants, narrow with risk_score_max first.

The response reports scannedApps, failedApps, and truncated so you can read an empty result correctly. failedApps counts apps whose drill-down errored and was skipped — most often devices on a stream that is not fed by Defender for Endpoint, where every device drill-down fails. In that case the entities map comes back empty even though apps were scanned, so check failedApps before concluding "no results": a high failedApps count means the scan could not attribute apps, not that the entity uses none. truncated flags that more apps existed beyond max_apps and were not scanned.

Parameter	Type	Required	Description
stream_id	string	✓	Stream ID.
entity_type	string	✓	users or devices.
entity_identifier	string	—	Focus a single user identifier or device name; omit for the full matrix.
connection_id	string	—	Target Entra tenant.
period	string	—	P7D, P30D, or P90D. Default P30D.
max_apps	number	—	Apps to scan. Default 25, ceiling 100.
risk_score_max	integer	—	Only scan apps at or below this risk score — recommended on large tenants.

Example prompt.

"What cloud apps does jane@example.com use, and how risky are they?"

See Also

For Defender alerts, incidents, and Advanced Hunting (including the CloudAppEvents table for event-level cloud app activity), see Microsoft Cloud — Security. For Intune-detected apps on managed devices, see Microsoft Cloud — Intune.