ALM.Xpp.PpacMCP

Standalone MCP (Model Context Protocol) server for managing Power Platform Admin Center (PPAC) and D365 Finance & SCM environments via any MCP-capable AI assistant (GitHub Copilot, Claude, Cursor, etc.).

Wraps d365bap.tools and the Power Platform CLI (pac).
Exposes 78 tools in two transport modes: stdio (local) and HTTP (cloud/agents).

See TOOLS.md for the complete, per-tool reference with all parameters.
Source: github.com/alimbenhelal-pro/ALM.XPP.PPACMCP

Quick start

30 seconds from zero to your first PPAC query in VS Code:

1. Install & run

# Install PowerShell modules (once per machine)
Install-Module d365bap.tools, Az, PSFramework -Scope CurrentUser -Force

# Clone and build
git clone https://github.com/alimbenhelal-pro/ALM.XPP.PPACMCP
cd ALM.Xpp.PpacMCP
dotnet build

2. Register as an MCP server in VS Code (.vscode/mcp.json)

{
  "servers": {
    "ppac": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "C:\\path\\to\\ALM.Xpp.PpacMCP"]
    }
  }
}

3. Connect and query (in GitHub Copilot or any MCP client)

ppac_bap_connect                                              → browser login
ppac_bap_configure_tenant id="Prod" upn="admin@contoso.com" tenantId="<guid>"
ppac_bap_list_environments                                    → list all environments
ppac_bap_get_environment envId="my-sandbox"                   → inspect a specific environment

PAC CLI tools (solutions, flows, connectors) also need: ppac_pac_auth_create_sp → ppac_pac_auth_select.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  ALM.Xpp.PpacMCP                                            │
│                                                             │
│  ┌─────────────────────┐   ┌──────────────────────────┐    │
│  │  d365bap.tools layer│   │  PAC CLI layer            │    │
│  │  (PS Runspace)      │   │  (pac.exe via Runspace)   │    │
│  │  Az session state   │   │  PAC auth profiles        │    │
│  └─────────────────────┘   └──────────────────────────┘    │
│                                                             │
│  Transport : stdio (local) │ HTTP/SSE (cloud)               │
└─────────────────────────────────────────────────────────────┘

Two independent auth layers:

• d365bap.tools uses Az PowerShell (Connect-AzAccount / Service Principal)
• PAC CLI uses its own pac auth profiles (pac auth create)
  Both must be initialised before using their respective tools.

Prerequisites

# PowerShell 7
winget install Microsoft.PowerShell

# .NET 9 SDK
winget install Microsoft.DotNet.SDK.9

# d365bap.tools layer — PS modules (once per machine)
Install-Module d365bap.tools -Scope CurrentUser -Force
Install-Module Az             -Scope CurrentUser -Force
Install-Module PSFramework    -Scope CurrentUser -Force

# PAC CLI layer
winget install Microsoft.PowerPlatformCLI
# OR: dotnet tool install --global Microsoft.PowerApps.CLI.Tool

Dependencies

NuGet packages (.csproj)

PowerShell modules (runtime — Install-Module)

External CLI tools

Two modes

Cloud env vars

PPAC_TRANSPORT=http
PPAC_PORT=7291
PPAC_TENANT_ID=<azure-tenant-guid>
PPAC_CLIENT_ID=<app-registration-client-id>
PPAC_CLIENT_SECRET=<client-secret>
PPAC_API_KEY=<optional-key-protecting-/mcp>

Build & run

# Local (stdio)
cd ALM.Xpp.PpacMCP
dotnet run

# Cloud (HTTP) — local test
$env:PPAC_TRANSPORT="http"; $env:PPAC_PORT="7291"; dotnet run

# Self-contained publish
dotnet publish -c Release -r win-x64 --self-contained true -o publish

MCP client config

VS Code — local stdio (.vscode/mcp.json)

{
  "servers": {
    "ppac": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "C:\\path\\to\\ALM.Xpp.PpacMCP"]
    }
  }
}

VS Code — cloud HTTP (.vscode/mcp.json)

{
  "servers": {
    "ppac": {
      "type": "http",
      "url": "http://localhost:7291/mcp",
      "headers": { "X-API-Key": "<PPAC_API_KEY>" }
    }
  }
}

VS Code — published binary (.vscode/mcp.json)

{
  "servers": {
    "ppac": {
      "type": "stdio",
      "command": "C:\\path\\to\\publish\\ALM.Xpp.PpacMCP.exe"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "ppac": {
      "command": "C:\\path\\to\\publish\\ALM.Xpp.PpacMCP.exe"
    }
  }
}

Copilot Studio / Azure agent — cloud HTTP

Point the agent's MCP connector to:
https://<your-host>/mcp with header X-API-Key: <PPAC_API_KEY>

Auth flow

Local mode (interactive)

# d365bap.tools layer
ppac_bap_connect               →  Connect-AzAccount (browser or device-code)
  OR ppac_bap_connect_sp       →  Service Principal (clientId + clientSecret)
ppac_bap_configure_tenant      →  register alias (persists across sessions) and activate immediately
ppac_bap_switch_tenant         →  switch between registered aliases (if needed)
ppac_bap_check_connection      →  verify Az session is active

# PAC CLI layer (independent)
ppac_pac_auth_create           →  pac auth create (browser)
  OR ppac_pac_auth_create_sp   →  pac auth create --service-principal
ppac_pac_auth_select           →  pac auth select --index N
ppac_pac_org_who               →  verify active PAC connection

Cloud mode (automatic)

d365bap.tools auth is handled automatically at startup via PPAC_TENANT_ID / PPAC_CLIENT_ID / PPAC_CLIENT_SECRET.
PAC CLI auth must be initialised once via ppac_pac_auth_create_sp + ppac_pac_auth_select.

Tool reference

See TOOLS.md for the full per-tool reference with all parameters and examples.

Key combined scenarios

1. Full environment provisioning (0 portal clicks)

ppac_bap_create_environment
  → ppac_pac_auth_create_sp             (PAC profile for new env)
  → ppac_pac_dv_solution_import         (base solutions)
  → ppac_bap_fno_toggle_virtual_entity  (activate F&O entities)
  → ppac_bap_confirm_fno_dv_integration (verify F&O↔Dataverse link)
  → ppac_bap_dv_add_user + ppac_bap_assign_role (onboard users)

2. Database refresh + automatic recovery

ppac_bap_set_admin_mode (enable=true, confirm=true)
ppac_bap_fno_database_refresh (source=PROD, target=UAT, confirm=true)
  → poll ppac_bap_list_operations until "Succeeded"
ppac_pac_dv_solution_import              (re-import customizations wiped by refresh)
ppac_bap_fno_refresh_virtual_entity_metadata (re-sync F&O schema)
ppac_bap_confirm_fno_dv_integration      (verify F&O link)
ppac_bap_set_admin_mode (enable=false)   (restore user access)

3. ALM promotion DEV → UAT → PROD

ppac_pac_dv_solution_deploy (source=DEV, target=UAT, managed=true, confirm=true)
ppac_bap_confirm_fno_dv_integration (UAT)
ppac_bap_compare_environments (UAT vs PROD — detect config drift)
ppac_pac_dv_solution_deploy (source=UAT, target=PROD, managed=true, confirm=true)
ppac_bap_fno_refresh_virtual_entity_metadata (PROD)
ppac_bap_dv_publish_customizations (PROD)

4. Cross-env drift audit

ppac_bap_compare_environments            (config diff)
ppac_pac_dv_solution_list                (solution versions — run for each env)
ppac_bap_fno_compare_virtual_entities    (virtual entity diff)
ppac_bap_compare_users                   (user/role diff)
ppac_pac_dv_connector_list               (connector diff — run for each env)

5. Security & compliance audit

ppac_bap_list_security_roles             (all roles in env)
ppac_bap_list_role_members               (who has SysAdmin?)
ppac_bap_list_users                      (all accounts incl. system)
ppac_pac_dv_connector_list               (external connections)
ppac_bap_list_graph_group_members        (Entra group membership)
ppac_bap_list_app_users                  (service principals registered)

6. Post-refresh USERINFO recovery (JIT SQL)

ppac_bap_fno_get_jit_access (role="Writer", cacheId="refresh")
ppac_bap_fno_userinfo_manage (action="list-disabled", jitCacheId="refresh")
ppac_bap_fno_userinfo_manage (action="enable", networkAlias="admin@contoso.com", jitCacheId="refresh")
ppac_bap_fno_userinfo_manage (action="disable-all-except", networkAlias="admin@contoso.com", jitCacheId="refresh", confirm=true)
ppac_bap_fno_launch_db_ssms (jitCacheId="refresh")   ← optional SSMS verification

Security

• All user-supplied parameters are sanitised (' → '') before PowerShell execution.
• No credentials are stored — d365bap.tools auth uses Az PowerShell's standard token cache (~/.azure/).
• PAC CLI auth profiles are stored in the OS credential store (pac auth list).
• ppac_bap_fno_database_refresh is destructive (overwrites target DB) — protected by confirm=true guard.
• ppac_pac_dv_solution_delete and ppac_bap_set_admin_mode require confirm=true.
• PPAC_API_KEY in HTTP mode protects /mcp — store it in Azure Key Vault / GitHub Secrets, never in code.

Troubleshooting

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.