Querying

---
name: "microsoft-graph-querying"
description: >
  The RAG query loop for the Microsoft Graph MCP Server for Enterprise —
  microsoft_graph_suggest_queries to retrieve vetted candidate Graph calls,
  microsoft_graph_get to execute them, microsoft_graph_list_properties for entity
  schema — with worked identity and directory examples, result-presentation
  guidance, and the read-only, RBAC-scoped, rate-limited constraints on what comes
  back.
when_to_use: >-
  When asked any question about a tenant's users, groups, applications, devices, licenses, sign-in
  activity, or directory roles that should be answered through the Microsoft Graph MCP server —
  count users, find guests, find inactive accounts, audit MFA registration, list app inventory,
  check license usage. Use when: microsoft graph query, query entra, how many users, guest users,
  inactive accounts, users without mfa, license usage, app inventory, directory roles, suggest
  queries, graph get, or list properties.
---

# Querying Microsoft Entra with the Graph Enterprise MCP

The Microsoft Graph MCP Server for Enterprise is **not** a raw Graph API passthrough. It is built around a Retrieval-Augmented-Generation (RAG) workflow: you describe what you want, the server hands you vetted candidate API calls from a curated catalog, and you execute the one that fits. Following this loop is the difference between correct answers and made-up endpoints.

## Anti-triggers

Three plugins reach the same Microsoft 365 tenant with near-identical
vocabulary. This one answers questions; it cannot change anything.

- **Any change to the tenant** — this server issues `GET` only, so
  there is no write path to fall back on. A single-tenant change
  (disable an account, assign a licence, set out-of-office) belongs to
  the `m365` plugin; a packaged multi-tenant action (offboard, reset
  MFA, revoke sessions) belongs to the `cipp` plugin.
- **Fleet-wide questions** — "across all our tenants" needs a
  multi-tenant control plane, not one delegated token scoped to one
  signed-in user in one consented tenant; use the `cipp` plugin
  (`cipp-tenants`, `cipp-standards`).
- **A tenant that authenticates but returns nothing** — that is
  per-tenant admin consent, not a bad query; use
  `microsoft-graph-connection`.

The short rule: **ask one tenant → this skill; change one tenant →
`m365`; do either across the fleet → `cipp`.**

## The core rule

**Always start with `microsoft_graph_suggest_queries`. Do not invent raw Graph endpoints.**

Microsoft Graph is enormous and its URL/`$filter`/`$select` syntax is full of sharp edges (advanced query parameters, `ConsistencyLevel` headers, OData casts). The `suggest_queries` tool exists precisely so the model doesn't have to guess. Hand-writing a Graph URL and passing it to `microsoft_graph_get` is an error pattern — even when you "know" the endpoint, route through `suggest_queries` so you get the catalog's correct, tested form.

## The three tools

| Tool | Role in the loop |
|------|------------------|
| `microsoft_graph_suggest_queries` | RAG search over a curated catalog of Graph API examples. Input: a natural-language intent. Output: candidate Graph API calls (endpoint, parameters, description) ranked by relevance. |
| `microsoft_graph_get` | Executes a read-only Graph `GET`. Input: a Graph API call (ideally one returned by `suggest_queries`). Honors the caller's roles, granted scopes, and Graph throttling. |
| `microsoft_graph_list_properties` | Returns the schema for a Graph entity — its properties and relationships. Use it when you need to know what's selectable before constructing or refining a call. |

## The query loop

```
1. suggest_queries(intent)   → candidate Graph calls
2. (model)  select the candidate that best matches the question
3. get(selected candidate)   → data
4. (optional) list_properties(entity)  → schema, to refine $select or pick the right entity
5. (model)  translate the JSON result into a plain-language answer
```

Steps 2 and 5 are *your* job — `suggest_queries` proposes, the model disposes. When several candidates look plausible, prefer the one whose description most precisely matches the user's intent and whose parameters you can fill confidently. If a candidate needs a property you're unsure exists, call `list_properties` first.

## Worked examples

### "How many users are in the tenant?"

1. `microsoft_graph_suggest_queries("count of all users in the tenant")` → returns candidates such as a call against the `users` collection with a count.
2. Pick the candidate that returns a count rather than a full user list (cheaper, directly answers the question).
3. `microsoft_graph_get(<that candidate>)`.
4. Answer: "Contoso has **412** licensed and unlicensed user accounts in Entra ID."

### "Which users don't have MFA registered?"

1. `microsoft_graph_suggest_queries("users who have not registered for multi-factor authentication")` → expect candidates around authentication-methods registration reporting (admin reporting surface).
2. The right candidate is typically a user-registration-details report filtered to users where MFA is not registered — not a per-user method enumeration.
3. `microsoft_graph_get(<that candidate>)`.
4. If you need to also show each user's department or job title, call `microsoft_graph_list_properties("user")` to confirm those properties, then re-suggest/refine.
5. Answer with a named list and a count: "9 of 412 accounts have no MFA method registered — including 2 with admin roles, which is the priority to fix."

### "List the guest (external) users."

1. `microsoft_graph_suggest_queries("external guest users in the directory")` → candidates filtering the `users` collection on guest user type.
2. `microsoft_graph_get(<that candidate>)`.
3. Answer with the guest accounts, their invitation/external state, and a count. Flag guests with no recent sign-in as cleanup candidates.

### "Find inactive accounts that still hold Copilot licenses."

This needs two reads joined by the model:

1. `microsoft_graph_suggest_queries("user accounts with no recent sign-in activity")` → an inactive-users / sign-in-activity reporting candidate. Run it with `microsoft_graph_get`.
2. `microsoft_graph_suggest_queries("users assigned a Microsoft 365 Copilot license")` → a licensed-users candidate. Run it with `microsoft_graph_get`.
3. The model intersects the two result sets: accounts that appear in both are inactive *and* Copilot-licensed — wasted spend.
4. Answer with the overlap list and the reclaimable license count.

> The example endpoints above are illustrative of what `suggest_queries` typically returns — don't hard-code them. Always run `suggest_queries` for the live, tenant-appropriate candidate.

## Using `list_properties`

Call `microsoft_graph_list_properties` when you need the schema of an entity — for example to know whether `user` exposes `signInActivity`, `assignedLicenses`, or `createdDateTime`, or what relationships `group` has. Use it to:

- choose the right `$select` properties so a `get` returns exactly what the question needs;
- confirm an entity actually has the field you're about to filter on;
- decide which entity to query when a question could map to several (`user` vs `servicePrincipal` vs `device`).

## Constraints to respect

- **Read-only.** Everything here reports. There is no way to create, edit, or delete directory objects through this server. If the user asks for a change, say so and point them to a write-capable tool (e.g. the `cipp` plugin).
- **RBAC-honoring.** Results are scoped to the signed-in caller's Entra roles and the app's granted scopes. If a query returns less than expected, it may be a permissions boundary, not missing data — and per-tenant admin consent must already be in place (see the `microsoft-graph-connection` skill).
- **Rate limit.** 100 calls/min/user plus Graph's own throttling. Don't fan out speculative `get` calls — `suggest_queries` exists so one good call beats ten guesses.
- **Preview.** The example catalog and behavior may change; verify anything material in the Entra admin center.

## Presenting results

Raw Graph JSON is not an answer. Always translate: lead with the direct answer (a count, a yes/no, a named list), then supporting detail, then — if it's an audit-style question — a recommendation. Non-technical readers should never see GUIDs or JSON unless they ask.