MCP Server
GrantFlow runs a Model Context Protocol (MCP) server, so an AI assistant can answer questions about your tenant and carry out administrative tasks on your behalf. You can ask it "who can become Domain Admin?", "which managed accounts fail rotation?" or "make Anna eligible for the Tier 1 Server Admin role", and it calls GrantFlow's tools to answer or to act.
The server is at:
https://mcp.grantflow.cloud/mcpThe assistant always acts as the person who signed in. GrantFlow applies that person's own GrantFlow role, checks every call exactly as it checks the portal and the CLI, and records every call in the audit log under their name. Your tenant comes from that sign-in. No tool takes a tenant argument, and nobody can reach another tenant's data through the server.
This guide is for administrators. It covers connecting a client, how changes are confirmed, the full tool reference and the audit trail.
What You Can Do and Who Can Do It
The server offers tools in eleven areas: directory lookups, access analysis, roles, eligibility, activations, managed accounts, policies, connectors, remote sessions, SIEM connections and sign-in identity. The tool reference lists every tool.
What a caller sees depends on their GrantFlow role, the same User and Admin roles you assign in Entra ID Tenant Setup:
- Admin: all 40 tools.
- User: only
auth_whoami. The assistant tells a User that administrative tools are offered only to GrantFlow administrators.
Hiding a tool is not the only safeguard. If a call reaches a tool its caller may not use, GrantFlow still refuses it. The assistant sees a plain "not found", and the audit log records the call as denied.
Some tasks stay in the GrantFlow web app on purpose. The assistant cannot approve or deny activation requests, create SIEM feed tokens, enroll tunnel agents, retry a failed access removal, move a session target to another zone, or clear an account's policy. When a task needs one of these, the assistant points you to the web app.
Connect a Client
Any MCP client that supports OAuth sign-in can connect. You enter the server URL and sign in with your work account from your Entra ID tenant. You do not configure a client ID or a scope: GrantFlow's server handles the OAuth exchange with Entra ID and always requests access to the GrantFlow API on your behalf. The sign-in goes through the same GrantFlow web app as the portal, so a tenant that completed Entra ID Tenant Setup needs no further consent.
- In your MCP client, add a remote MCP server (in Claude, a custom connector) with the URL
https://mcp.grantflow.cloud/mcp. - Connect. Your client opens a Microsoft sign-in page.
- Sign in with your work account. Your Conditional Access policies apply as for any GrantFlow sign-in.
- Ask "Who am I signed in as?". The assistant calls
auth_whoamiand reports your tenant, your name and whether you hold the Admin role.
GrantFlow accepts sign-ins only from clients it has approved, such as Claude on the web and desktop and local clients that sign in through a loopback address. If your client's sign-in is refused, contact info@grantflow.cloud.
Connecting through InfraScout
InfraScout's AI chat can register GrantFlow's MCP server so that each chat user calls GrantFlow as themselves. This needs a different setup, done once by an administrator of your tenant. See Connect GrantFlow's MCP server to InfraScout.
How Changes Are Confirmed
Most write tools work in two steps. The assistant first calls the tool without confirming and gets back a preview: what would change, who is affected and whether GrantFlow would refuse the change. A preview changes nothing.
GrantFlow instructs the assistant to show you the preview and stop, and to confirm only after you agree in a reply to that preview, never in the same turn. Your original request does not count as agreement, and an assistant running unattended, with nobody to reply, is told to report the preview and stop. These are instructions to the assistant: GrantFlow itself cannot tell whether a person agreed, and it accepts a confirm that carries the right IDs. Use an assistant you trust to follow them.
A few details matter when you read a preview or its result:
- Confirm by ID. A preview resolves the names you used to exact IDs, and the confirm sends those IDs back. If several people, accounts or activations match, the assistant lists the candidates and asks you to pick one. It never picks one itself.
- The previewToken. For
account_policy_assignandsiem_connection_revoke, the preview also returns apreviewToken, which the assistant sends back unchanged when it confirms. If anything changed between the preview and the confirm, GrantFlow refuses the confirm and the assistant previews again. - Pending means queued. Changes that reach your directory run as queued jobs. A confirmed
activation_end,account_rotate_password,account_checkout_endoraccount_checkin_resolveanswers pending, which means queued, not done. The assistant checks the outcome afterwards with the matching list or get tool. - A sync is pending until it finishes.
connector_syncanswers pending once the sync has started. The assistant then checksconnector_listuntil the connector's last sync time moves past the start.
Some writes apply at once, without a preview, by design: creating a role, linking people to a managed account, starting a connector sync, creating session zones and session targets, and managing session folders. The tool reference marks each write tool's behavior in its Preview column. Some of these grant privilege immediately: role_create, because a role's targets are a privilege grant, and account_link, because each link lets that person check out the account's password. account_add does the same when it links people to the new account without setting a policy, because it previews only when it sets one. Agree the people, the account and the targets with the assistant before it runs them.
Read the preview
A preview is the moment to catch a wrong person, role or account. Check the names and the counts before you agree, especially for anything that grants privilege, such as an eligibility or a new role target.
Tool Reference
Every tool except auth_whoami needs the Admin role. Read tools change nothing. In the Preview column, Always means the tool previews before every change, Sometimes means it previews only for the riskier changes described, and No means it writes at once.
Directory
The directory tools read GrantFlow's synced copy of your Active Directory and Entra ID. Results say when that copy was last synced, so the assistant can tell you how current an answer is.
| Tool | What it does | Type | Preview |
|---|---|---|---|
directory_find | Finds users, groups and Entra roles by exact identifier (UPN, email, SID, object ID, DOMAIN\name) or by part of a name. | Read | — |
Access
| Tool | What it does | Type | Preview |
|---|---|---|---|
access_for_principal | Shows everything one person can do: eligible roles and why, activations, pending requests and linked managed accounts. | Read | — |
access_standing_privilege | Finds people who hold the groups and Entra roles your GrantFlow roles grant permanently, without an activation that explains it. | Read | — |
GrantFlow reports standing privilege but does not remove it. You remove those memberships in the directory.
Role
| Tool | What it does | Type | Preview |
|---|---|---|---|
role_list | Lists GrantFlow roles with their maximum duration, approval policy and directories. | Read | — |
role_get | Shows one role in full: its targets, privilege level, Tier-0 targets, approval policy and the machines it grants for remote sessions. | Read | — |
role_access | Shows who is eligible for one role and who holds it right now. | Read | — |
role_create | Creates a role with its targets, privilege level, maximum duration and approval policy. | Write | No |
role_update | Changes a role's name, description, duration, privilege level, approval policy, targets and session targets. | Write | Sometimes: removing targets, changing the approval policy, or adding targets to a role that anyone is eligible for or waiting on, or that has a Tier-0 target |
role_delete | Deletes a role together with its targets and every eligibility for it. Refused while activations are in effect or requests await approval. | Write | Always |
A GrantFlow role is a bundle of privileges, not an Entra ID directory role. See Role Management.
Eligibility
| Tool | What it does | Type | Preview |
|---|---|---|---|
eligibility_grant | Makes up to 20 people or groups eligible for a role. | Write | Always |
eligibility_revoke | Removes a person's or group's direct eligibility for one role or for every role. Activations in effect are not ended. | Write | Always |
Activation
| Tool | What it does | Type | Preview |
|---|---|---|---|
activation_list | Lists activations in effect now, requests awaiting approval, or recent history. | Read | — |
activation_end | Ends an activation before its end time, removes the directory access, ends the remote sessions it authorized and notifies the holder. | Write | Always |
Account
| Tool | What it does | Type | Preview |
|---|---|---|---|
account_list | Lists managed accounts with their policy, rotation health and current checkout. Filters by health, such as failed or overdue rotation. | Read | — |
account_get | Shows one managed account in full: policy, checkout state, recent password rotations, linked users and roles. | Read | — |
account_checkout_list | Lists checkouts: who holds which account, until when, and failed check-ins. | Read | — |
account_add | Puts a directory account under GrantFlow management, optionally with a policy and the people who may check it out. | Write | Sometimes: when it sets a policy |
account_link | Lets up to 20 people check out a managed account. | Write | No |
account_unlink | Stops people checking out a managed account. An open checkout is not ended. | Write | Always |
account_policy_assign | Puts up to 20 managed accounts under an account policy. | Write | Always, with a previewToken |
account_remove | Stops managing an account. The directory account itself is not changed. | Write | Always |
account_rotate_password | Rotates a managed account's password now. | Write | Always |
account_checkout_end | Ends someone's checkout now, with the roles activated under it and the remote sessions using it. | Write | Always |
account_checkin_resolve | Closes a failed check-in after you dealt with the account in the directory. The assistant asks you what happened to it. | Write | Always |
See Account Checkout for how checkouts work.
Policy
| Tool | What it does | Type | Preview |
|---|---|---|---|
policy_list | Lists approval policies with their approvers, or account policies with their rotation interval, rotation window and checkout limit. | Read | — |
Connector
| Tool | What it does | Type | Preview |
|---|---|---|---|
connector_list | Lists your directory connectors, when each last synced, and for Active Directory whether its agents are online. | Read | — |
connector_sync | Starts a sync of one connector now, so recent directory changes reach GrantFlow. It changes nothing in the directory. | Write | No |
Session
The session tools cover remote sessions over RDP, SSH and VNC. When session management is switched off for your environment, they answer that the feature is disabled.
| Tool | What it does | Type | Preview |
|---|---|---|---|
session_setup_status | Shows how far remote-session setup is and the next step for each incomplete zone. | Read | — |
session_zone_list | Lists session zones with their networks, machines, tunnel agents and default file transfer setting. | Read | — |
session_target_list | Lists the machines users reach by remote session, the roles granting each and their file transfer setting. | Read | — |
session_folder_list | Lists the folders that organize machines on the Sessions page. | Read | — |
session_zone_create | Creates a session zone for one network segment. | Write | No |
session_target_add | Adds machines to a zone. Nobody can reach them until a role grants them. | Write | No |
session_folder_create | Creates a folder. | Write | No |
session_folder_update | Renames a folder or moves it under another parent. | Write | No |
session_folder_delete | Deletes an empty folder. | Write | No |
session_target_set_folder | Moves up to 100 machines into a folder or out of their folder. | Write | No |
Folders grant nothing and change no access, which is why their tools need no preview. To grant machines to people, the assistant uses role_update. See Session File Transfer for the file transfer fields.
SIEM
| Tool | What it does | Type | Preview |
|---|---|---|---|
siem_connection_list | Lists the SIEM connections that pull your audit log, with a state such as pulling, stalled or revoked. | Read | — |
siem_connection_revoke | Revokes a SIEM connection's feed token. That SIEM stops receiving events. Cannot be undone. | Write | Always, with a previewToken |
Feed tokens are created only in the web app. If someone pastes a feed token into the chat, the assistant does not repeat it: it asks which connection the token belongs to and offers to revoke it by name. See SIEM Integration.
Auth
| Tool | What it does | Type | Preview |
|---|---|---|---|
auth_whoami | Shows who you are signed in as: tenant, user, display name, whether you hold the Admin role, and how long your sign-in lasts. Available to every user. | Read | — |
Limits and Refusals
MCP calls count against your tenant's request budget together with calls from the portal and the CLI. When the budget is spent, GrantFlow refuses the call before it changes anything and tells the assistant when to retry.
If an action needs a stronger sign-in than your current session has, GrantFlow refuses it, and the assistant asks you to do it in the web app, where you can step up. See Step-up Authentication.
Audit Trail
Every tool call writes one event to your audit log, attributed to the person who signed in:
mcp.readfor a read tool, in thereadcategory.mcp.writefor a write tool, in thechangecategory. Previews, refused calls and failed confirms are recorded too.
Each event carries the tool's name, the arguments it was called with (cleaned and length-limited), and the outcome: ok, not_found, ambiguous, invalid_argument, denied, conflict, disabled, rate_limited or internal. A write event also records whether the call was a preview and how many items ended in each state. A confirm in which every item failed is recorded as failed.
When a confirmed write changes something, GrantFlow also records the usual event for that change, such as an eligibility grant or an activation end, exactly as if you had made it in the portal. All of these events carry the channel mcp, so you can separate assistant activity from portal and CLI activity. They appear in Audit Events and in your SIEM through the audit feed.