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)

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_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

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.