ALM.XPP.PPACMCP
ALM.Xpp.PpacMCP is a standalone MCP server for administering Power Platform and Dynamics 365 Finance & SCM environments through AI clients such as GitHub Copilot, Claude, and Cursor. It wraps d365bap.tools and the Power Platform CLI to expose operational tasks like tenant authentication, environment management, D365 app lifecycle, user and security
Ask AI about ALM.XPP.PPACMCP
Powered by Claude Β· Grounded in docs
I know everything about ALM.XPP.PPACMCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.toolsuses 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)
| Package | Version | Links |
|---|---|---|
ModelContextProtocol | 1.0.0 | NuGet Β· GitHub (MCP C# SDK) |
ModelContextProtocol.AspNetCore | 1.0.0 | same SDK (GitHub) |
Microsoft.Extensions.Hosting | 9.0.7 | NuGet |
Microsoft.PowerShell.SDK | 7.4.6 | NuGet Β· GitHub |
System.Text.Json | 10.0.3 | NuGet |
PowerShell modules (runtime β Install-Module)
| Module | Links |
|---|---|
d365bap.tools | GitHub Β· PS Gallery |
Az | GitHub Β· PS Gallery |
PSFramework | GitHub Β· PS Gallery |
External CLI tools
| Tool | Links |
|---|---|
Power Platform CLI (pac) | Docs Β· GitHub |
Two modes
| Local (stdio) | Cloud (HTTP) | |
|---|---|---|
| Env var | PPAC_TRANSPORT=stdio (default) | PPAC_TRANSPORT=http |
| Transport | JSON-RPC over stdin/stdout | Streamable HTTP on PPAC_PORT (default 7291) |
| Auth | Interactive: ppac_bap_connect (browser/device-code) or ppac_bap_connect_sp | Auto: SP via env vars at startup |
| Use with | VS Code, Claude Desktop, Cursor | Azure Container Apps, Copilot Studio, CI/CD agents |
| Endpoint | β | http://host:7291/mcp + /healthz |
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.
| Group | Count | Tools (excerpt) |
|---|---|---|
| Auth | 6 | ppac_bap_connect ppac_bap_connect_sp ppac_bap_configure_tenant ppac_bap_switch_tenant ppac_bap_list_tenants ppac_bap_check_connection |
| Environments | 12 | ppac_bap_list_environments ppac_bap_get_environment ppac_bap_compare_environments ppac_bap_create_environment ppac_bap_set_admin_mode ppac_bap_fno_database_refresh β¦ |
| D365 Apps & Ops | 7 | ppac_bap_list_d365_apps ppac_bap_install_d365_app ppac_bap_fno_list_platform_updates ppac_bap_fno_apply_platform_update ppac_bap_list_operations ppac_bap_start_all_app_updates β¦ |
| Users & Security | 15 | ppac_bap_list_users ppac_bap_compare_users ppac_bap_list_security_roles ppac_bap_list_role_members ppac_bap_assign_role ppac_bap_dv_list_teams β¦ |
| Virtual / Solutions / DB | 8 | ppac_bap_fno_list_virtual_entities ppac_bap_fno_toggle_virtual_entity ppac_bap_fno_compare_virtual_entities ppac_bap_dv_list_solutions ppac_bap_dv_publish_customizations β¦ |
| UDE Developer Tools | 10 | ppac_bap_fno_get_jit_access ppac_bap_fno_userinfo_manage ppac_bap_fno_launch_db_ssms ppac_bap_fno_get_ude_dev_files ppac_bap_fno_get_ude_connection β¦ |
| PAC CLI β Auth | 5 | ppac_pac_auth_create ppac_pac_auth_create_sp ppac_pac_auth_list ppac_pac_auth_select ppac_pac_org_who |
| PAC CLI β Solutions ALM | 10 | ppac_pac_dv_solution_list ppac_pac_dv_solution_export ppac_pac_dv_solution_import ppac_pac_dv_solution_deploy ppac_pac_dv_solution_check β¦ |
| PAC CLI β Apps / Flows | 4 | ppac_pac_dv_canvas_list ppac_pac_dv_connector_list ppac_pac_dv_flow_list ppac_pac_dv_flow_set |
| Helpers | 1 | ppac_get_options |
| Total | 78 |
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_refreshis destructive (overwrites target DB) β protected byconfirm=trueguard.ppac_pac_dv_solution_deleteandppac_bap_set_admin_moderequireconfirm=true.PPAC_API_KEYin HTTP mode protects/mcpβ store it in Azure Key Vault / GitHub Secrets, never in code.
Troubleshooting
| Symptom | Fix |
|---|---|
Run Connect-AzAccount first | Call ppac_bap_connect or ppac_bap_connect_sp |
d365bap.tools not found | Install-Module d365bap.tools -Scope CurrentUser -Force |
PSFramework not found | Install-Module PSFramework -Scope CurrentUser -Force |
| Server exits on startup | Check stderr β PS module import errors are logged there |
ppac_bap_configure_tenant has no effect | Restart the MCP server; the tool saves and activates the tenant immediately |
pac: command not found | winget install Microsoft.PowerPlatformCLI then restart terminal |
| PAC tool returns 401/Unauthorized | Call ppac_pac_auth_create_sp + ppac_pac_auth_select |
| PAC wrong environment | Call ppac_pac_org_who to verify, then ppac_pac_auth_select |
| SP auth fails in cloud mode | Check PPAC_CLIENT_ID / PPAC_CLIENT_SECRET; verify App Registration has Dynamics CRM + PowerApps API permissions |
| JIT access denied | Ensure the environment is UDE/USE type and JIT is enabled in the admin portal |
Contributing
See CONTRIBUTING.md.
License
MIT β see LICENSE.
