Showing a thunk in the Claude desktop app: a guide for AI agents

This guide is for AI agents running in the Claude desktop app (or in a
cloud session linked to the user's computer) that work on thunks through the
Thunk.AI FDA MCP. It covers how to open a thunk in the app's browser
pane and keep the pane on what you are working on. Why you show the thunk, and
which view to show for each change, are in
Building thunks with the FDA MCP
(Open the thunk in the browser pane). For the Codex desktop app, read
Showing a thunk in the Codex desktop app
instead.

At the start of a session

Open the tenant's Thunk.AI app in the browser pane and complete steps 3–5 of
Open and keep the pane (site approval, sign-in, a visible pane) before
building, so the user approves and signs in once, up front. The tenant's app
is the site of any thunk url the FDA MCP returns (for example from
the thunk list).

Do this in the first turn where you will build, change or run a thunk,
before the first create call, not after the thunk exists. A turn that only
explains Thunk.AI doesn't need it. If the pane shows the sign-in screen, the
user can sign in while you build, so they can see the thunk when it first
appears.

Open and keep the pane

The browser pane's tools are named mcp__Claude_Browser__* in a desktop
session and mcp__remote-devices__Claude_Browser__* in a cloud session linked
to the user's computer. This guide names them by the part after that prefix.

Load the tools in one call. If the browser-pane tools are deferred, load
them all with one ToolSearch whose query is the full prefix, with
max_results: 64. If the only tool present is
enable__mcp__remote-devices__Claude_Browser, call it first.
Reuse an existing tab. Call tabs_context. If a tab is already on the
thunk URL's site, navigate that tab (its tabId) to the thunk URL.
Otherwise call preview_start with the thunk URL.
Handle site approval. If the call says the site isn't allowed yet and
the session has request_access, call it with the site's URL (such as
https://<the thunk URL's host>) and scope "site", so it isn't asked
again in later sessions. Wait for the answer, then retry once. If it is
declined, or there is no request_access, say so in one line and carry on.
Check the page. Use read_page, or take one small screenshot
(computer, scale 0.5). This checks the state of the pane (a banner, the
sign-in screen), not how the thunk is configured.
- If a cookie banner shows, choose the most privacy-preserving option
  ("Only Essential").
- If the Thunk.AI sign-in screen shows (it may say "Your session
  expired"), never sign in on the user's behalf. Tell them in plain words,
  and in the visible text of your reply, not only in a status line or
  tool output. Say that the panel beside the chat is asking them to sign
  in to Thunk.AI with Google or Microsoft, that they need to do it once
  (the pane keeps its own sign-ins, separate from their regular browser),
  and that you carry on building in the meantime. For example: "The panel
  on the right is asking you to sign in to Thunk.AI. Sign in once with
  Google or Microsoft and you'll see the thunk there. I'll keep building
  meanwhile."
- Until the user is signed in, don't say "open it in the pane", "watch it
  in the pane" or "click … in the pane". Repeat the one-line sign-in ask
  in the closing message (or next-step box) of each turn that points at
  the app. Check the page again when they say they've signed in, or
  before you next point at the pane.
- If the user can't or won't sign in yet (for example, while IT reviews
  the tool), show what the pane would have shown as text in the chat
  instead: the steps, the test results, the output. Don't point at the
  app again unless they ask.
Make sure they can see it. If tabs_context reports the pane as
hidden, tell the user to press Cmd+Shift+B (Mac) or Ctrl+Shift+B
(Windows), or to close what's in the side panel and click the globe icon.
Opening a page does not bring a hidden pane forward on its own.
If the pane can't be reached (no browser tools after the load, or calls
error or time out), tell the user in one line that the Claude app's browser
isn't reachable and that they can open the thunk link themselves. Don't
retry, and don't switch to Claude in Chrome unless they ask.
Keep it current. Navigate the same tab as you work, following
Show each change in the pane in
Building thunks with the FDA MCP. Don't open
a new tab for each view.