Grant-EntraBetaMcpServerPermission

Grant-EntraBetaMcpServerPermission

    -ApplicationName <String>
    [<CommonParameters>]

Grant-EntraBetaMcpServerPermission

    -ApplicationId <Guid>
    [<CommonParameters>]

Grant-EntraBetaMcpServerPermission

    -ApplicationName <String>
    -Scopes <String[]>
    [<CommonParameters>]

Grant-EntraBetaMcpServerPermission

    -ApplicationId <Guid>
    -Scopes <String[]>
    [<CommonParameters>]

The Grant-EntraBetaMcpServerPermission cmdlet grants delegated permissions to a Model Context Protocol (MCP) client for accessing the Microsoft MCP Server for Enterprise. This cmdlet works with a predefined MCP client (Visual Studio Code, Visual Studio, ChatGPT, or Claude) or a custom MCP client specified by its application ID.

The cmdlet creates an OAuth2 permission grant that allows the specified MCP client to access the Microsoft MCP Server for Enterprise on behalf of users. When the -Scopes parameter is specified, the cmdlet operates in additive mode, adding the specified scopes to any existing grant while preserving other previously granted scopes. Without the -Scopes parameter, the cmdlet grants all available scopes (replacing any existing grant). The cmdlet returns an OAuth2PermissionGrant object that conforms to the Microsoft Graph API resource specification.

For delegated scenarios, the calling user needs at least one of the following Microsoft Entra roles:

• Cloud Application Administrator
• Application Administrator
• Privileged Role Administrator

Connect-Entra -Scopes 'Application.ReadWrite.All', 'Directory.Read.All', 'DelegatedPermissionGrant.ReadWrite.All'
$grant = Grant-EntraBetaMcpServerPermission -ApplicationName 'VisualStudioCode'
$grant

Operating on MCP client: Visual Studio Code
Granting all available scopes: MCP.AccessReview.Read.All, MCP.AdministrativeUnit.Read.All, MCP.Application.Read.All ...

✓ Successfully granted permissions to Visual Studio Code
  Grant ID: aaaaaaaa-bbbb-cccc-1111-222222222222

Id                                   ClientId                             ResourceId                           ConsentType   Scope
--                                   --------                             ----------                           -----------   -----
aaaaaaaa-bbbb-cccc-1111-222222222222 client-sp-id-1234                    resource-sp-id-5678                  AllPrincipals MCP.AccessReview.Read.All, MCP.AdministrativeUnit.Read.All, MCP.Application.Read.All ...

This example grants all available delegated permissions (illustrative subset shown) to Visual Studio Code and returns the OAuth2PermissionGrant object. NOTE: The output scopes in the above example are shortened for readability.

Connect-Entra -Scopes 'Application.ReadWrite.All', 'Directory.Read.All', 'DelegatedPermissionGrant.ReadWrite.All'
$grant = Grant-EntraBetaMcpServerPermission -ApplicationName 'VisualStudioCode' -Scopes 'MCP.User.Read.All', 'MCP.AccessReview.Read.All'
$grant.Scope

Operating on MCP client: Visual Studio Code
Adding specific scopes (preserving existing grant): MCP.AccessReview.Read.All, MCP.User.Read.All

✓ Successfully granted permissions to Visual Studio Code
  Grant ID: dddddddd-eeee-ffff-4444-555555555555

MCP.AdministrativeUnit.Read.All MCP.AccessReview.Read.All MCP.User.Read.All

This example adds specific scopes (MCP.AccessReview.Read.All and MCP.User.Read.All) to Visual Studio Code's existing grant. Note that the existing MCP.AdministrativeUnit.Read.All scope is preserved (additive mode).

Connect-Entra -Scopes 'Application.ReadWrite.All', 'Directory.Read.All', 'DelegatedPermissionGrant.ReadWrite.All'
$customClientId = '12345678-1234-5678-9012-123456789012'
$grant = Grant-EntraBetaMcpServerPermission -ApplicationId $customClientId
Write-Host "Grant created with ID: $($grant.Id)"

Operating on MCP client: Custom MCP Client
Granting all available scopes: MCP.AdministrativeUnit.Read.All MCP.AccessReview.Read.All MCP.User.Read.All

✓ Successfully granted permissions to Custom MCP Client
  Grant ID: eeeeeeee-ffff-aaaa-5555-666666666666

Grant created with ID: eeeeeeee-ffff-aaaa-5555-666666666666

This example grants all available permissions (illustrative subset) to a custom MCP client identified by its service principal ID.

Connect-Entra -Scopes 'Application.ReadWrite.All', 'Directory.Read.All', 'DelegatedPermissionGrant.ReadWrite.All'
$grant = Grant-EntraBetaMcpServerPermission -ApplicationName 'Claude' -Scopes 'MCP.User.Read.All', 'MCP.AdministrativeUnit.Read.All'
$grant | Select-Object Id, ClientId, ResourceId, ConsentType, Scope

Operating on MCP client: Claude
Adding specific scopes (preserving existing grant): MCP.AdministrativeUnit.Read.All, MCP.User.Read.All

✓ Successfully granted permissions to Claude
  Grant ID: ffffffff-aaaa-bbbb-6666-777777777777

Id                                   ClientId         ResourceId       ConsentType   Scope
--                                   --------         ----------       -----------   -----
ffffffff-aaaa-bbbb-6666-777777777777 claude-sp-id     resource-sp-id   AllPrincipals MCP.AdministrativeUnit.Read.All MCP.User.Read.All

This example adds specific scopes to M365 MCP Client for Claude in additive mode and displays selected properties of the returned OAuth2PermissionGrant object.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

You can't pipe objects to this cmdlet.

Returns an OAuth2PermissionGrant object that represents the delegated permission grant. This object conforms to the Microsoft Graph API OAuth2PermissionGrant resource type and contains the following key properties:

• Id: Unique identifier for the permission grant.
• ClientId: Object ID of the client service principal.
• ResourceId: Object ID of the resource service principal (Microsoft MCP Server for Enterprise).
• ConsentType: Set to "AllPrincipals" for admin consent.
• Scope: Space-separated list of granted permission scopes.
• PrincipalId: Null (since consentType is AllPrincipals).

The scopes string is normalized by sorting and de-duplicating the provided scope values before persisting.

• The cmdlet processes one MCP client at a time and returns an OAuth2PermissionGrant object for that client.
• The cmdlet automatically creates service principals for the resource and client applications if they don't exist.
• Additive mode: When the -Scopes parameter is specified, the cmdlet adds the specified scopes to any existing grant while preserving other previously granted scopes.
• Replace mode: When -Scopes is not specified, all available delegated scopes from the resource application are granted, replacing any existing grant.
• The cmdlet validates all specified scopes against the available scopes on the resource application and throws an error if any invalid scopes are provided.
• The cmdlet requires specific Microsoft Graph scopes: Application.ReadWrite.All, Directory.Read.All, and DelegatedPermissionGrant.ReadWrite.All.
• The returned OAuth2PermissionGrant object conforms to the Microsoft Graph API resource specification.