Install a feedback widget

Create a Deck feedback widget and install the Feedback SDK in the product, so in-product feedback flows into Deck.

This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth.

Use it when: the user says "add a feedback button to our app", "collect in-app feedback in Deck" or "install the Deck SDK".
Outcome: an active widget exists in Deck, the product sends feedback to it through the @deck-io/feedback SDK, and one test submission shows in Deck.
Needs: Deck MCP, the product codebase in this session, and a publishable key that the user creates in Settings → Deck Collect SDK. Any role with MCP access can create a widget.

1. Probe Deck MCP

Call get_user_context. This must be a real tool call.

401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop.
No Deck tools: fetch and follow https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md. Stop this workflow until the tools work.

2. Check the widgets that exist

Call list_widgets with status: "active". A widget collects feedback from one surface of the product. If an active widget already fits the surface, use it and skip step 4.

3. Ask what to build

Skim the codebase first. Then ask the user, and wait for the answers:

Where must feedback appear? Name the pages, surfaces or user actions.
Thumbs up or down, free text, or both?
The SDK's built-in dialog, or the product's own UI with headless submit?
Link the widget to a Deck Project? Call list_projects with query to find it. Only feedback that arrives after the link goes to that Project.

Show the widget name and the Project link, and get a yes. Then call create_feedback_widget with name (1-255 characters) and optional project_id. Read the new widget_id.

An identical call within 24 hours returns the first widget and creates nothing new.

5. Get the install details

Call explore_widgets with widget_id. Read:

install_prompt: the install steps for a coding agent, with the SDK docs links.
publishable_keys: the active keys, as masked prefixes only.
settings_url: the link to Settings → Deck Collect SDK.

If publishable_keys is empty, tell the user to create a key at settings_url. Deck shows the full key one time only.

The user puts the key in the app environment. Browser and React code read NEXT_PUBLIC_DECK_PUBLISHABLE_KEY, or the Vite equivalent. Server-only code reads DECK_PUBLISHABLE_KEY. Do not ask the user to paste the key into the chat. Never ask for a dk_ API key. The SDK does not use one.

6. Install the SDK

Follow install_prompt. Use the answers from step 3. Read the SDK overview and the Feedback SDK docs that install_prompt lists before you write code.

Add @deck-io/feedback with the package manager of the repo.
Add DeckProvider near the root, with publishableKey from the environment variable.
Pass the current user with a stable product user ID.
Mount FeedbackDialog, ThumbsFeedback or the headless submit, with widgetId set to the new widget ID.
Use the auth, env and style patterns that the repo already has.

Show the planned changes and get a yes before you change files. Do not commit a key to the repo.

7. Test it

Ask the user to run the product and send one test feedback through the widget. Then make these calls at the same time:

explore_widgets with widget_id. Read feedback_counts and recent_submissions.
list_sources with source: "widget". The new widget feedback shows first.

Deck processes widget feedback into insights in batches, so insights can come later. If nothing arrives, read the troubleshooting page of the Feedback SDK docs.

Rules

Show the plan and get a yes before you call write tools or change code.
No Deck tool creates, shows or revokes a full publishable key. The user manages keys in Settings → Deck Collect SDK.
To rename the widget or change its Project link, call update_feedback_widget.
archive_feedback_widget cannot be undone. The widget stops accepting feedback. Call it only when the user asks, and get a yes each time.
Keep the SDK context small: use IDs and enums, not personal data. Keep the default URL capture, which leaves out query strings and hash fragments.
Quote Deck's numbers. Do not compute your own.
If the user has more than one Deck organization, call select_organization first and pass org_id on every call.

Done when

The widget is active in Deck and has a Deck link.
The SDK is installed, and the user knows which files changed and which environment variables to set.
One test submission shows in explore_widgets.

See also: SDKs, Projects and Model Context Protocol.