/renderdoc-mcp

name: renderdoc-mcp
description: Analyze RenderDoc GPU frame captures with renderdoc-mcp MCP tools. Use when Codex needs to inspect .rdc captures, diagnose black screens or visual artifacts, explain frame structure, inspect specific draw calls, or investigate GPU rendering and performance issues.

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:

| Tool | What it tells you | |------|-------------------| | `get_capture_info` | API, GPU, driver, event count | | `get_stats` | Per-pass draw and triangle counts, top draws, largest resources | | `get_log` | Validation errors and debug messages; check HIGH severity first | | `list_passes` | Frame structure: pass names and draw counts |

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:

| User goal | Workflow | |-----------|----------| | "Screen is black" or "nothing renders" | Black Screen Diagnosis | | "Colors are wrong" or "there are artifacts" | Visual Artifact Diagnosis | | "Performance is bad" or "too slow" | Performance Analysis | | "Explain what this frame does" | Frame Walkthrough | | "Debug this specific draw call" | Targeted Draw Inspection | | "Compare two captures" or "what changed between frames" | Frame Regression Diagnosis | | General or unclear request | Ask the user what they want to investigate |

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** /