fix(mcp): preview errors tell agents what to do instead

[t3dotgg]

On headless hosts, preview tools fail with "MCP credential does not grant the preview capability" or "No active preview tab". Agents could not tell what to do next, so they retried or gave up.

What Changed

The error messages now name the next step. Agents read these messages directly as the tool result.

• Browser access off (PreviewAutomationUnavailableError): do not retry. Use a headless browser from the shell, such as Playwright, or curl. The user can turn on "Agent browser access" in Settings.
• No desktop app connected (PreviewAutomationNoAvailableHostError): preview tools run in a connected T3 Code desktop app, and a headless server has no browser. Do not retry. Use a shell browser, or ask the user to open the thread in the desktop app.
• No tab (PreviewAutomationTabNotFoundError): call preview_open first.

preview_snapshot has its own failure path that showed only the error tag, for example Preview snapshot failed: PreviewAutomationUnavailableError. It now shows the message for preview errors, in both the text and structuredContent. Clients differ in which one they show the model. These messages come from the server, never from page output, so nothing from the browser leaks.

Checklist

• This PR is small and focused
• I explained what changed and why

Tested with vp test run on the MCP server, invocation context, broker, and preview toolkit tests. Server and contracts typecheck and lint are clean.

Made with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Preview automation errors now provide situation-specific next steps, including when to use a headless browser, enable browser access, connect a desktop, or open a preview.
  • Errors distinguish between an explicitly requested tab that cannot be found and the absence of an active tab, and advise when to omit the tab request.
  • Preview snapshot failures include the server-provided message in both text and structured error details when available.

[macroscopeapp]

Approvability

Verdict: Approved at dd3431e

Macroscope's review found this PR approvable — This is a small MCP-focused fix that improves existing preview error responses with actionable fallback instructions while leaving successful behavior and existing non-preview fallbacks unchanged. The updated production paths are covered by focused tests, with no product-default, schema-breaking, deployment, or static-analysis changes.

Notes:

• All code in this push has already been reviewed. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.5 KiB	13.5 KiB	+12 B (+0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.1 KiB	7.1 KiB	−1 B (−0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+13 B (+0.2%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	56.2 KiB	56.2 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	9	9	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.5 KiB	−8 B (−0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.1 KiB	7.1 KiB	−4 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.4 KiB	6.4 KiB	−4 B (−0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.0 KiB	57.0 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	9	9	0 (0.0%)	21	✅

Baseline: 4f27a84 · PR result: dd3431e · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 114.0 KiB
• Claude decoded thread snapshot: 114.7 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: e2b63c4c-48c7-4ed2-9f08-2a3464ec912d

📥 Commits

Reviewing files that changed from the base of the PR and between 1e52a34 and 6a33362.

📒 Files selected for processing (1)

• apps/server/src/mcp/McpHttpServer.ts

Included review availability: 5 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

📝 Walkthrough

Walkthrough

Preview automation errors now provide operation-specific recovery guidance. MCP snapshot responses include the message when the first failure is a preview automation error. Other failures continue to use the error tag.

Changes

Preview automation errors

Layer / File(s)	Summary
Add recovery guidance to preview errors packages/contracts/src/previewAutomation.ts	Unavailable-capability and no-host errors advise against retrying and provide alternatives. Tab-not-found errors distinguish a specified missing tab from the absence of an active tab and describe next steps.
Return preview error messages in MCP snapshot responses apps/server/src/mcp/McpHttpServer.ts, apps/server/src/mcp/McpHttpServer.test.ts, apps/server/src/mcp/McpInvocationContext.test.ts	For a recognized preview automation failure, snapshot responses include its message in text and structured content. Tests check the returned message and recovery guidance.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 6a333

The preview responses provide recovery guidance without exposing renderer-supplied diagnostics. No unresolved merge risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: improving MCP preview error messages with actionable guidance.
Description check	✅ Passed	The description explains the problem, the error-specific changes, and the testing performed. It includes the required What Changed and Checklist sections. The Why information appears in the introducto…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 4…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

Dismissing prior approval to re-evaluate dd3431e