Analyze DirectX Dump Files with AI agents

PIX includes two tools for inspecting a DirectX Dump File with an AI agent without opening the PIX UI:

  • DxDmp.exe is a command-line interface (CLI) that returns dump data as text, JSON, or Markdown.
  • DxDmpMcp.exe is a Model Context Protocol (MCP) server that exposes the same diagnostic data as tools and keeps dumps open across related queries.

Both tools use the PIX API and read .dxdmp files. Use them to investigate GPU hangs, page faults, shader faults, resource lifetime problems, and queue synchronization problems.

For reference information about DxDmp.exe and DxDmpMcp.exe, see DxDmp tools reference.

Prerequisites

  • Install a version of PIX that includes the DxDmp tools.
  • Get the DirectX Dump File that you want to investigate. For more information about creating a dump, see Generate DirectX Dump Files.
  • Use an AI agent that can run local commands or connect to a local MCP server.

PIX is usually installed under %ProgramFiles%\Microsoft PIX\<version>\, or under Microsoft PIX Preview\<version>\ for preview builds. DxDmp.exe and DxDmpMcp.exe are in the PIX installation folder.

Make the DxDmp tools available to your agent

An agent can access DxDmp through either the CLI or the MCP server:

Interface How the agent uses it
DxDmp CLI The agent runs DxDmp.exe through its shell tools. The CLI requires no MCP configuration. For targeted queries, the agent can request concise text or Markdown, limit the output, or write large results to a file.
DxDmp MCP server The agent calls protocol-native tools exposed by DxDmpMcp.exe. The server keeps one or more dumps open across related requests.

Both interfaces provide the same dump evidence, and both can limit large results. Choose the CLI for shell-based access and concise output. Choose the MCP server to keep dumps open and use protocol-native tools during a multi-step investigation. The pix-diagnose skill provides the workflow for either interface.

You can also use DxDmp.exe without an AI agent. Scripts, build systems, and crash-triage pipelines can request JSON output and process the results with conventional automation.

For CLI access, add the PIX installation folder to PATH, or tell the agent the full path to DxDmp.exe. For example, in PowerShell:

$pixInstall = "$env:ProgramFiles\Microsoft PIX\<version>"
$env:PATH = "$pixInstall;$env:PATH"
DxDmp.exe --help

Replace <version> with the installed PIX version. This change applies to the current PowerShell session.

Install the PIX diagnosis skill

PIX includes a host-agnostic pix-diagnose skill. Install it to give your agent the recommended diagnostic workflow. The skill explains how to avoid queries for missing data and how to distinguish application bugs from driver or hardware bugs.

The skill is under Tools\DxDmp\agent-kit\skills\pix-diagnose in the PIX installation folder. For example, to install it for GitHub Copilot CLI, run this command from the PIX installation folder:

Copy-Item -Recurse Tools\DxDmp\agent-kit\skills\pix-diagnose $HOME\.copilot\skills\

The adjacent Tools\DxDmp\agent-kit\knowledge folder contains diagnostic methodology, common application-bug patterns, and known hardware issues. The MCP server exposes this knowledge base through tools. For CLI use, allow the agent to read the PIX installation folder if the host restricts filesystem access.

Configure MCP access

The agent can diagnose dumps through the CLI after you install the skill and make DxDmp.exe available. To use MCP instead, register DxDmpMcp.exe as a local stdio server in an MCP-compatible host.

MCP configuration formats vary by host, but a typical entry has this shape:

{
  "mcpServers": {
    "pix-dxdmp": {
      "command": "C:\\Program Files\\Microsoft PIX\\<version>\\DxDmpMcp.exe",
      "args": ["--transport", "stdio"]
    }
  }
}

Replace <version> with the installed PIX version. In GitHub Copilot CLI, use /mcp to manage MCP server configuration.

The server supports the local standard input/output (stdio) transport. Because stdio is the default and only supported value, --transport stdio is optional.

With the MCP server configured, the skill can use its tools instead of invoking the CLI.

Ask the agent to diagnose a dump

Give the agent the dump path and tell it what you need to decide:

Diagnose C:\Dumps\GpuHang.dxdmp with the PIX DxDmp tools.
The compiled shader objects are under D:\Build\Shaders.
The shader PDBs are under \\Symbols\Game\Release.
Determine whether this is an application bug or a driver or hardware bug.
Explain the evidence, give a confidence level, and recommend the next action.

The pix-diagnose skill guides the agent to:

  • Identify which diagnostic data is present before requesting details.
  • Follow the evidence that matches the type of GPU failure.
  • Limit and page large results so that they don't overwhelm the agent's context.
  • Consult the packaged knowledge base after identifying the GPU and symptoms.
  • Correlate evidence across the dump before assigning the problem to the application, driver, or hardware.
  • Report when the dump doesn't contain enough data for a reliable diagnosis.

You don't need to choose individual DxDmp commands or MCP tools.

Provide shader object and PDB paths

DxDmp doesn't automatically use the shader object and PDB search paths configured in the PIX UI. To map a fault back to DXIL or HLSL, tell the agent where to search for files from the exact build that produced the dump:

  • The compiled shader object (.cso, .dxbc, or .dxil).
  • The matching shader PDB for HLSL source.

The dump records a hash for each shader wave. The agent uses that hash and its filesystem tools to find a likely compiled shader object in the location that you provide. It then passes the exact object path to DxDmp.

DxDmp reads the compiled object and passes it to the PIX API for the selected wave. The API verifies that the object matches the shader in the dump and uses it to provide DXIL. To provide HLSL, the agent also passes the exact path to the matching PDB. A mismatched object or PDB doesn't resolve shader source.

Without these locations, the agent can still use the data in the dump. It might ask for the files if shader source would improve the diagnosis.

Troubleshoot agent setup

Problem Action
The agent can't find DxDmp.exe. Add the PIX installation folder to PATH, or give the agent the full executable path.
The agent doesn't see the DxDmp MCP tools. Check the MCP server path and arguments, and restart or reconnect the agent host.
The agent can't read the dump, knowledge base, shader object, or PDB. Allow the agent host to access those paths, and tell the agent where the shader objects and PDBs are.
The agent reports that important dump sections are absent. The dump might be partial. Create another dump with the required driver and DRED collection options, if possible. For more information about creating a dump, see Generate DirectX Dump Files.
The agent can't resolve HLSL. Provide the shader object and PDB from the same build that generated the dump.

Related content

  • Last updated on