get_preview

Build the live preview and public page URLs for a registry item. Returns four variants — docs page, isolated iframe preview, dark-palette variant, and macOS-frame screenshot variant.

get_preview_url is the agent's way to show the user what the block actually looks like, not just describe it.

When to use

The user wants to eyeball a component before installing ("show me hero-announcement first").
A vision-capable agent wants to feed the preview URL into its pipeline to visually compare candidates.
Returning a link in chat so the user can open it in a browser.
Generating screenshots for documentation (the ?framed=1 variant is what the internal screenshot scripts use).

How it works

Pure string assembly — no I/O beyond the initial getRegistryItem lookup. The tool:

Resolves the item via getRegistryItem(name) to get its homepage and files[0].path.
Extracts the surface (blocks, ai, components, …) from the homepage URL.
For blocks, parses the category out of files[0].path (blocks/{category}/{slug}.tsx) — the preview route is nested as /preview/blocks/{category}/{slug}, even though the public page is flat.
For other surfaces, the preview route is /preview/{surface}/{slug}.
Builds four variants:
- page — docs/marketing page (/blocks/hero-announcement)
- preview — isolated iframe (/preview/blocks/hero/hero-announcement)
- previewDark — same preview with ?theme=dark
- previewFramed — same preview with ?framed=1 (macOS browser frame treatment)

Runs in microseconds after the registry lookup resolves.

Arguments

Name	Type	Required
`name`	`string`	✓

Response

{
  "name": "pricing-grouped-comparison-table",
  "page": "https://www.shadcn.io/blocks/pricing-grouped-comparison-table",
  "preview": "https://www.shadcn.io/preview/blocks/pricing/pricing-grouped-comparison-table",
  "previewDark": "https://www.shadcn.io/preview/blocks/pricing/pricing-grouped-comparison-table?theme=dark",
  "previewFramed": "https://www.shadcn.io/preview/blocks/pricing/pricing-grouped-comparison-table?framed=1"
}

If the item resolves but doesn't have a surface we can map (rare), the tool returns a MCP-standard error.

Example prompts

use shadcnio get_preview_url for hero-announcement and share the link with me

use shadcnio get_preview_url for pricing-grouped-comparison-table — I want to see it in dark mode

use shadcnio to give me preview URLs for the 6 @related alternatives of hero-gradient-headline

Manual invocation

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_preview_url","arguments":{"name":"pricing-grouped-comparison-table"}}}' \
  | sed -n 's/^data: //p' | jq '.result.content[0].text | fromjson'

Tips + gotchas

Blocks' preview URLs are nested; public URLs are flat. That's why this tool is worth having — agents never have to guess which variant to use.
The four URL variants are all public. No token required, no Pro gating. Safe to paste in any chat.
Screenshot script compatibility. The ?framed=1&theme=dark combo is exactly what the bun run screenshot:* scripts use to capture the gallery images. If you're building tooling around these previews, match that pattern.
Non-block surfaces don't always have a preview route. If the deployment hasn't wired /preview/{surface}/{slug} for every type, the tool still emits the URL — it may 404 in the browser. page is the safe fallback.