fxray

An X-ray for Power Fx: an MCP server that wraps the Power Platform CLI (pac) so Claude, GitHub Copilot (VS Code agent mode) or any MCP client can inspect and work with Power Apps solutions, canvas app source and Dataverse: list and export solutions, read canvas apps as text (screens, controls, Power Fx formulas, data sources), read table / column / relationship metadata, run read-only FetchXML, diff two solution versions, run the solution checker, and (gated, dry-run by default) pack, import and publish.

Safety model

• Environment allowlist. Live tools only reach environments listed in allowed_environments. Every call passes --environment explicitly, so pac's currently selected org is never used implicitly, and whoami and every write re-check that the org pac actually connected to is allowlisted. An empty allowlist (or no config file) disables every live tool; offline tools still work.
• Read-only by default. pack_solution, import_solution and publish_customizations default to dry_run=true and return a plan plus the exact pac command. Executing needs allow_writes = true in the config and dry_run=false on the call. Have the assistant show you the plan first.
• Imports default to mode="update" (never deletes). upgrade (managed only) is explicit and flagged as deleting components missing from the zip. Blockers (managed/unmanaged mismatch, managed downgrade, empty DatabaseReferences) stop execution. Before importing over an unmanaged solution the current one is exported to out/backups/<env>/ and the result carries an undo recipe; managed targets cannot be exported, which the plan says.
• Local output (exports, unpacks, packs, checker results) goes under output_dir; protected_paths are never written to.
• FetchXML is read-only by nature; it is parsed and validated (well-formed, no DOCTYPE, one entity) before it reaches pac.
• No secrets in the config: pac keeps its own auth profiles. pac's signed checker-results URL is not returned.

Install

pip install fxray          # or run it without installing: uvx fxray

Needs Python 3.11+ and the Power Platform CLI:

dotnet tool install --global Microsoft.PowerApps.CLI.Tool         # needs the .NET SDK
pac auth create --environment https://yourorg.crm.dynamics.com/   # a person, in a terminal (browser sign-in)

fxray finds pac on PATH, then at ~\.dotnet\tools\pac.exe (the dotnet global-tool folder); the Windows MSI install's pac.cmd shim is resolved to the pac.exe it wraps. MCP clients often start servers with a shorter PATH than your terminal, so if pac works in a terminal but not in fxray, set pac_path to the full path. Tested on Windows with pac 2.9.3. pac is a .NET tool and runs on macOS/Linux too; fxray should, but that is untested.

Interactive sign-in is impossible from an MCP server: when pac's token expires the tools say so and stop, and a person runs pac auth create (or pac auth select) again in a terminal.

Configure

Copy fxray.example.toml to fxray.toml and list the environments fxray may reach. Lookup order (first file found wins):

1. $FXRAY_CONFIG (an explicit path; an error if it does not exist)
2. $FXRAY_WORKSPACE\fxray.toml
3. .\fxray.toml (the folder the MCP client starts the server in)
4. %LOCALAPPDATA%\fxray\fxray.toml (Windows; ~/.config/fxray/fxray.toml elsewhere; override the folder with $FXRAY_HOME)

The per-user file is the simplest choice: then FXRAY_CONFIG is not needed at all. The file is re-read on every call (no restart needed).

allowed_environments = ["https://contoso-dev.crm.dynamics.com/"]
allow_writes = false
output_dir = "out"

Register

Claude Code:

claude mcp add --scope user fxray -- uvx fxray
# or, with the config somewhere other than the per-user folder:
claude mcp add --scope user fxray -e FXRAY_CONFIG=C:\path\to\fxray.toml -- uvx fxray

VS Code / Copilot. Add the server to the user-level %APPDATA%\Code\User\mcp.json so it works from every window (a workspace .vscode/mcp.json only loads once you trust that workspace's MCP servers):

{
  "servers": {
    "fxray": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fxray"],
      "env": { "FXRAY_CONFIG": "C:\\path\\to\\fxray.toml" }
    }
  }
}

Drop the env block if the config is in the per-user folder. Then ask the assistant to run pac_status: it shows which config file was used, which pac was found and its version, and pac's auth profiles (each flagged as allowlisted or not).

Tools

source = a solution .zip, an unpacked solution folder (pac solution unpack / export_solution), a canvas .msapp, or a pac canvas unpack --layout SourceCode folder (Src/*.pa.yaml + .msapr). Offline tools need no pac.

Typical flow: list_solutions → export_solution (zip + unpacked folder) → read offline with source= that folder: solution_components, describe_table, canvas_overview, search_formulas, canvas_data_sources → change the source → pack_solution → import_solution (dry run, then for real) → publish_customizations.

Traps it checks for

Canvas apps kept as source (a generator or hand-maintained .pa.yaml, packed with pac solution pack and imported) fail in ways Studio does not show: