renderdoc-mcp

RenderDoc MCP

Use renderdoc-mcp to analyze GPU frame captures and debug rendering problems.

Always use the MCP server named renderdoc-mcp for tool calls.

When you need shell-based or batch workflows outside the MCP tool surface, use renderdoc-cli from PATH.

Analysis Framework

Every analysis task follows this flow:

1. Understand goal -> what does the user want to know?
2. Open and gather -> load the capture and collect context in parallel
3. Route -> pick the right diagnostic workflow
4. Execute -> drill down with verification at each step
5. Summarize -> present findings with evidence

Phase 1: Open and Gather Context

Opening a Capture

From file: call open_capture with the .rdc path.

From app: call capture_frame to launch the app, inject RenderDoc, capture a frame, and auto-open it.

Verification: check the returned event count. If it is 0, the capture is empty and you should report that immediately.

Error recovery:

• If open_capture fails, verify the path exists and points to a valid .rdc file.
• If capture_frame fails, check the executable path, whether the app needs admin privileges, whether it exits immediately, and whether delayFrames should be increased.

Initial Context Gathering

After a capture is open, call these tools in parallel because they are independent:

Before moving on, summarize:

• Which graphics API is in use?
• How many passes and draws are present?
• Are there any HIGH-severity validation errors?
• Which passes or draws look most expensive?

Use that summary as the working context for the rest of the analysis.

Phase 2: Route to a Workflow

Choose a workflow based on the user's goal:

Diagnostic Workflows

Black Screen Diagnosis

list_draws
  draws = 0?
    -> No geometry submitted. Check:
       - list_events for Clear or Dispatch events
       - get_log for pipeline creation or binding errors
       - report "No draw calls found" with likely causes
  draws > 0?
    -> goto_event for the last draw and get_pipeline_state in parallel
       no render target bound?
         -> report that output goes nowhere
       render target bound?
         -> export_render_target
            render target has content?
              -> likely a present or swapchain issue; inspect Present-related events
            render target is black?
              -> inspect bindings and shaders:
                 - get_bindings
                 - get_shader ps
                 - get_shader vs

Parallel opportunity: goto_event and get_pipeline_state can run in parallel when they target the same eventId.

Visual Artifact Diagnosis

Identify the problematic draw, either from the user or by exporting render targets
  -> goto_event for that draw
  -> get_pipeline_state and get_bindings in parallel
     - inspect blend state
     - inspect render target format
     - inspect bound textures
     - export suspicious textures when needed
     - inspect shaders:
       - get_shader ps mode=disasm
       - get_shader ps mode=reflect
       - search_shaders if you need similar shader matches

If multiple draws look suspicious, show the candidate event IDs and names, export their render targets, and ask the user which one looks wrong.

Performance Analysis

Start from get_stats
  -> inspect top draws by triangle count
  -> goto_event and get_draw_info for heavy draws
  -> inspect pipeline complexity with get_pipeline_state
  -> inspect shader reflection with get_shader vs/ps mode=reflect
  -> inspect oversized resources with get_resource_info
  -> inspect the heaviest pass with get_pass_info
  -> look for redundant draws with similar shaders and resources

Report issues by impact. For each one, state what it is, where it occurs, how severe it is, and what the likely improvement is.

Frame Walkthrough

list_passes
  -> for each important pass:
     - get_pass_info
     - goto_event for the first draw and get_pipeline_state in parallel
     - describe the pass inputs, shaders, and outputs
     - export_render_target to show the pass result
  -> end with a narrative from start to finish

Parallel opportunity: when passes are independent analysis tasks, inspect two or three in parallel.

Pixel-Level Diagnosis

When investigating why a pixel has the wrong color or is missing:

1. pick_pixel — Read the current pixel color to confirm the issue
2. pixel_history — Find which draws modified this pixel, check if any were culled/discarded
3. debug_pixel — Trace the fragment shader execution to find where the wrong value comes from
4. get_texture_stats — Check if input textures have unexpected ranges (NaN, all-zero, etc.)

Shader Debugging

When a draw produces wrong output:

1. debug_vertex / debug_pixel — Trace shader execution with mode="summary" first
2. If inputs look wrong, check bindings with get_bindings
3. If logic seems wrong, re-run with mode="trace" for step-by-step execution

Frame Regression Diagnosis

When comparing two captures to find rendering differences:

1. diff_open captureA captureB → Load both captures
2. diff_summary → Quick overview: any differences? Check divergedAt field
3. diff_draws → Which draws changed/added/removed?
4. diff_pipeline "MarkerPath" → What pipeline state changed at that draw?
5. diff_framebuffer with diffOutput → Pixel-level visual comparison
6. diff_close → Clean up

Targeted Draw Inspection

When the user specifies an event ID or draw name:

goto_event + get_pipeline_state + get_bindings in parallel
  -> describe:
     - vertex shader with get_shader vs mode=reflect
     - pixel shader with get_shader ps mode=reflect
     - bound textures from bindings
     - render targets from pipeline state
     - viewport from pipeline state
  -> go deeper when needed:
     - get_shader vs/ps mode=disasm
     - export_render_target
     - export_texture
     - get_draw_info

Verification Checkpoints

Apply these checks throughout the analysis:

Error Recovery

When to Ask the User

Ask before proceeding when:

• Multiple draw calls could be the source of the problem.
• The analysis is ambiguous and you need the user to confirm the most likely hypothesis.
• The user's goal is still unclear after initial context gathering.
• You found a likely root cause but need confirmation before narrowing further.

Do not ask when:

• The next diagnostic step is obvious.
• More data will clearly narrow the problem.
• Exporting an image or texture will give better evidence.

Tool Reference

Session

Navigation and Events

Pipeline and Bindings

Shaders

Resources and Passes

Info and Diagnostics

Export

Pixel & Debug

Shader Hot-Editing

Extended Export

CI Assertions

Diff / Comparison