replayio · BLamy · May 13, 2026
diff --git a/dist/claude-code/replayio/skills/replayio/SKILL.md b/dist/claude-code/replayio/skills/replayio/SKILL.md
@@ -173,6 +173,12 @@ If the browser is already running:
 
 First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Claude Code connects to the Replay HTTP MCP server configured in `.mcp.json`.
 
+## Replay MCP widgets
+
+Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks.
+
+When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection.
+
 ## Recording uploads are automatic
 
 You do **not** need to run `replayio list` or `replayio upload <id>` manually. The plugin's hooks handle uploads:

diff --git a/dist/codex/replayio/.codex-plugin/plugin.json b/dist/codex/replayio/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "replayio",
   "version": "0.1.0",
-  "description": "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through the connected Replay ChatGPT app, and auto-upload recordings when the browser closes or the turn ends.",
+  "description": "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through Replay MCP tools with rich inspector widgets, and auto-upload recordings when the browser closes or the turn ends.",
   "author": {
     "name": "Replay",
     "url": "https://replay.io"
@@ -19,11 +19,12 @@
   ],
   "skills": "./skills/",
   "apps": "./.app.json",
+  "mcpServers": "./.mcp.json",
   "hooks": "./hooks.json",
   "interface": {
     "displayName": "Replay.io",
-    "shortDescription": "Record browser sessions and analyze recordings",
-    "longDescription": "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through the connected Replay ChatGPT app.",
+    "shortDescription": "Record browser sessions and inspect Replay recordings",
+    "longDescription": "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through Replay MCP tools. In MCP Apps-aware hosts, Replay tool results can render rich debugging widgets for logpoints, console output, React trees, Redux state, network requests, screenshots, source code, profiles, and exception stacks.",
     "developerName": "Replay",
     "category": "Coding",
     "capabilities": [

diff --git a/dist/codex/replayio/.mcp.json b/dist/codex/replayio/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "replay": {
+      "type": "http",
+      "url": "https://dispatch.replay.io/mcp"
+    }
+  }
+}
diff --git a/dist/codex/replayio/README.md b/dist/codex/replayio/README.md
@@ -1,5 +1,27 @@
-# Replay.io Plugin
+# Replay.io (Codex)
 
-Generated from `src/` in the Replay.io agent plugins repo.
+Record browser sessions with the **Replay Browser** via Playwright CLI, inspect runs from the terminal, and use the **Replay MCP** server (`.mcp.json`) after a recording uploads. Hooks upload pending recordings when Playwright closes a session and when the Codex turn stops.
+
+## MCP widgets
+
+The Codex plugin exposes Replay MCP directly through `https://dispatch.replay.io/mcp`. That server can attach MCP Apps widget metadata to tool descriptors:
+
+- `_meta.ui.resourceUri` for MCP Apps-compatible hosts.
+- `_meta["openai/outputTemplate"]` as the ChatGPT/OpenAI compatibility alias.
+- `structuredContent` for widget rendering while preserving text `content` for model narration.
 
-This bundle includes the Replay browser skill, upload/cleanup scripts, and the platform-specific integration config for this target.
+When the backend returns Replay widget results, Codex can render inspector-style cards for logpoints, console messages, React trees, Redux state, network requests, screenshots, source views, profiles, and exception stacks.
+
+## What ships in this bundle
+
+| Component | Path |
+|-----------|------|
+| Plugin manifest | `.codex-plugin/plugin.json` |
+| Connected Replay app | `.app.json` |
+| Replay HTTP MCP server | `.mcp.json` |
+| Agent skill | `skills/replayio/SKILL.md` (+ `references/`) |
+| Hooks | `hooks.json` |
+| Scripts | `scripts/post_bash_upload.sh`, `scripts/stop_close_and_upload.sh`, `skills/replayio/scripts/playwright_cli.sh` |
+| Logo | `assets/replayio.svg` |
+
+Generated from `src/` in the Replay.io agent plugins repo.
diff --git a/dist/codex/replayio/skills/replayio/SKILL.md b/dist/codex/replayio/skills/replayio/SKILL.md
@@ -1,9 +1,9 @@
 ---
 name: "replayio"
-description: "Use when you need to record or inspect a Playwright CLI browser run in Replay, test a local app directly with Playwright CLI, or use the connected Replay app for deeper debugging of an uploaded recording."
+description: "Use when you need to record or inspect a Playwright CLI browser run in Replay, test a local app directly with Playwright CLI, or use the Replay MCP server for deeper debugging of an uploaded recording."
 ---
 
-# Replay Browser + Playwright CLI + Replay App
+# Replay Browser + Playwright CLI + Replay MCP
 
 Use `playwright-cli` with the Replay Browser whenever you need a recorded browser session. Recordings upload automatically — you do **not** need to run `replayio upload` yourself. Your only responsibility is to **close the browser when the test is complete**. The plugin's hooks handle the rest:
 
@@ -14,9 +14,9 @@ Always prefer closing explicitly — it gives faster feedback and ensures record
 
 ## Direct CLI first
 
-Use `playwright-cli` directly for live browser control and first-pass inspection. Do not reach for the connected Replay app just to click, type, snapshot, read console output, inspect network requests, take screenshots, read storage, or check cookies.
+Use `playwright-cli` directly for live browser control and first-pass inspection. Do not reach for the Replay MCP server just to click, type, snapshot, read console output, inspect network requests, take screenshots, read storage, or check cookies.
 
-Use the connected Replay app only after a recording has uploaded and you need deeper Replay-specific debugging, such as inspecting execution history, narrowing a time-travel debugging problem, or investigating details that the live CLI cannot answer.
+Use the Replay MCP server only after a recording has uploaded and you need deeper Replay-specific debugging, such as inspecting execution history, narrowing a time-travel debugging problem, or investigating details that the live CLI cannot answer.
 
 Useful direct commands:
 
@@ -171,7 +171,13 @@ If the browser is already running:
 
 ## Analyzing uploaded recordings
 
-First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the connected Replay app tools only when you need deeper Replay-specific debugging beyond direct CLI output. This plugin does not launch a local MCP server; app authentication and tool exposure are handled by the connected Replay app.
+First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Codex connects to the Replay HTTP MCP server configured in `.mcp.json`; the connected Replay app id remains available in `.app.json` for app-level authentication and compatibility.
+
+## Replay MCP widgets
+
+Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks.
+
+When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection.
 
 ## Recording uploads are automatic
 
@@ -195,7 +201,7 @@ replayio list
 - If the requested port was busy, use the actual port printed by the dev server.
 - If a browser exists but your commands are detached, use `list` then `attach`.
 - Prefer explicit commands like `fill`, `click`, `check`, and `press` over `eval` or `run-code`.
-- Prefer direct CLI inspection (`console`, `network`, `screenshot`, storage, cookies, `eval`) before using the connected Replay app.
+- Prefer direct CLI inspection (`console`, `network`, `screenshot`, storage, cookies, `eval`) before using the Replay MCP server.
 - If Replay authentication fails, run `replayio login` or reconnect the relevant Replay app/integration.
 
 ## References

diff --git a/dist/cursor/replayio/skills/replayio/SKILL.md b/dist/cursor/replayio/skills/replayio/SKILL.md
@@ -179,6 +179,12 @@ If the browser is already running:
 
 First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use the `replay` MCP server tools only when you need deeper Replay-specific debugging beyond direct CLI output. Cursor connects to the Replay HTTP MCP server configured in `mcp.json`.
 
+## Replay MCP widgets
+
+Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks.
+
+When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection.
+
 ## Recording uploads are automatic
 
 You do **not** need to run `replayio list` or `replayio upload <id>` manually. The plugin's hooks handle uploads:

diff --git a/dist/opencode/replayio/AGENTS.md b/dist/opencode/replayio/AGENTS.md
@@ -6,4 +6,5 @@ Use the Replay browser workflow when a task needs a recorded browser session.
 - Set `PWCLI` from the plugin-provided shell environment or skill instructions and use `"$PWCLI"` for browser commands.
 - Close the browser before reporting results: `"$PWCLI" --session="$SESSION" close`.
 - Use Replay analysis tools only after a recording has uploaded and direct CLI output is not enough.
+- If Replay MCP renders an inspector widget, use the widget as the primary debugging view and follow its point/source/component/request actions when useful.
 - If Replay MCP authentication fails, reconnect or sign in through the agent host and retry.
diff --git a/lib/connectors.ts b/lib/connectors.ts
@@ -15,7 +15,10 @@ export const connectors = {
   codex: {
     id: "codex",
     output: "dist/codex/replayio",
-    artifacts: [{ source: ".app.json", destination: ".app.json" }],
+    artifacts: [
+      { source: ".app.json", destination: ".app.json" },
+      { source: ".mcp.json", destination: ".mcp.json" },
+    ],
   },
   cursor: {
     id: "cursor",

diff --git a/lib/strategies/codex.ts b/lib/strategies/codex.ts
@@ -13,7 +13,7 @@ async function build(context: BuildContext, connector: Connector): Promise<void>
     name: plugin.name,
     version: plugin.version,
     description:
-      "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through the connected Replay ChatGPT app, and auto-upload recordings when the browser closes or the turn ends.",
+      "Record browser sessions with the Replay Browser via Playwright CLI, analyze recordings through Replay MCP tools with rich inspector widgets, and auto-upload recordings when the browser closes or the turn ends.",
     author: {
       name: plugin.developerName,
       url: plugin.homepage,
@@ -24,12 +24,13 @@ async function build(context: BuildContext, connector: Connector): Promise<void>
     keywords: replaceKeyword(plugin.keywords, "chatgpt-app"),
     skills: "./skills/",
     apps: "./.app.json",
+    mcpServers: "./.mcp.json",
     hooks: "./hooks.json",
     interface: {
       displayName: plugin.displayName,
-      shortDescription: "Record browser sessions and analyze recordings",
+      shortDescription: "Record browser sessions and inspect Replay recordings",
       longDescription:
-        "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through the connected Replay ChatGPT app.",
+        "Drive a real browser with Playwright CLI against the Replay Browser to capture time-travel debuggable recordings, auto-upload them on close, and analyze uploaded recordings through Replay MCP tools. In MCP Apps-aware hosts, Replay tool results can render rich debugging widgets for logpoints, console output, React trees, Redux state, network requests, screenshots, source code, profiles, and exception stacks.",
       developerName: plugin.developerName,
       category: "Coding",
       capabilities: ["Interactive", "Read", "Write"],
@@ -50,11 +51,39 @@ async function build(context: BuildContext, connector: Connector): Promise<void>
   await context.writeJson(path.join(out, "hooks.json"), claudeStyleHooks("${CLAUDE_PLUGIN_ROOT:-.}"));
   await context.writeSharedPluginFiles(out, {
     pwcliExport: '${CLAUDE_PLUGIN_ROOT:-$PWD/dist/codex/replayio}/skills/replayio/scripts/playwright_cli.sh',
-    titleSuffix: "Replay App",
-    analysisSurface: "the connected Replay app",
-    analysisTools: "the connected Replay app tools",
+    titleSuffix: "Replay MCP",
+    analysisSurface: "the Replay MCP server",
+    analysisTools: "the `replay` MCP server tools",
     authNote:
-      "This plugin does not launch a local MCP server; app authentication and tool exposure are handled by the connected Replay app.",
+      "Codex connects to the Replay HTTP MCP server configured in `.mcp.json`; the connected Replay app id remains available in `.app.json` for app-level authentication and compatibility.",
+    readme: `# ${plugin.displayName} (Codex)
+
+Record browser sessions with the **Replay Browser** via Playwright CLI, inspect runs from the terminal, and use the **Replay MCP** server (\`.mcp.json\`) after a recording uploads. Hooks upload pending recordings when Playwright closes a session and when the Codex turn stops.
+
+## MCP widgets
+
+The Codex plugin exposes Replay MCP directly through \`https://dispatch.replay.io/mcp\`. That server can attach MCP Apps widget metadata to tool descriptors:
+
+- \`_meta.ui.resourceUri\` for MCP Apps-compatible hosts.
+- \`_meta["openai/outputTemplate"]\` as the ChatGPT/OpenAI compatibility alias.
+- \`structuredContent\` for widget rendering while preserving text \`content\` for model narration.
+
+When the backend returns Replay widget results, Codex can render inspector-style cards for logpoints, console messages, React trees, Redux state, network requests, screenshots, source views, profiles, and exception stacks.
+
+## What ships in this bundle
+
+| Component | Path |
+|-----------|------|
+| Plugin manifest | \`.codex-plugin/plugin.json\` |
+| Connected Replay app | \`.app.json\` |
+| Replay HTTP MCP server | \`.mcp.json\` |
+| Agent skill | \`skills/replayio/SKILL.md\` (+ \`references/\`) |
+| Hooks | \`hooks.json\` |
+| Scripts | \`scripts/post_bash_upload.sh\`, \`scripts/stop_close_and_upload.sh\`, \`skills/replayio/scripts/playwright_cli.sh\` |
+| Logo | \`assets/replayio.svg\` |
+
+Generated from \`src/\` in the Replay.io agent plugins repo.
+`,
   });
 }
 

diff --git a/src/assets/mcp-widgets-demo.png b/src/assets/mcp-widgets-demo.png
diff --git a/src/content/agents.md b/src/content/agents.md
@@ -6,4 +6,5 @@ Use the Replay browser workflow when a task needs a recorded browser session.
 - Set `PWCLI` from the plugin-provided shell environment or skill instructions and use `"$PWCLI"` for browser commands.
 - Close the browser before reporting results: `"$PWCLI" --session="$SESSION" close`.
 - Use Replay analysis tools only after a recording has uploaded and direct CLI output is not enough.
+- If Replay MCP renders an inspector widget, use the widget as the primary debugging view and follow its point/source/component/request actions when useful.
 - If Replay MCP authentication fails, reconnect or sign in through the agent host and retry.
diff --git a/src/content/skill.md b/src/content/skill.md
@@ -173,6 +173,12 @@ If the browser is already running:
 
 First inspect the live run with direct `playwright-cli` commands. Once a recording has uploaded, use {{ANALYSIS_TOOLS}} only when you need deeper Replay-specific debugging beyond direct CLI output. {{AUTH_NOTE}}
 
+## Replay MCP widgets
+
+Replay MCP tool calls may return both text `content` for the model and `structuredContent` for an MCP Apps widget. In MCP Apps-aware hosts, prefer the rendered widget for dense debugging views such as Logpoint output, React component trees, Redux actions, network details, screenshots, source code, profiles, and exception stacks.
+
+When a widget is visible, use it as evidence instead of restating every detail in prose. Use follow-up actions or related Replay MCP tools when the widget points to a specific point, source, component, request, or stack frame that needs deeper inspection.
+
 ## Recording uploads are automatic
 
 You do **not** need to run `replayio list` or `replayio upload <id>` manually. The plugin's hooks handle uploads: