Getting started: your first MCP Apps widget

#The short answer

To create your first MCP Apps widget without code in Widgetry: sign in with Google, click Use template on one of the 13 templates in the gallery, adjust its sample data in the editor while the preview shows it as the chat will, write a description for the agent and click Publish. The widget becomes a show_<slug> tool on Widgetry's MCP endpoint. Connect that endpoint to your agent, or link the widget from your own MCP server, and ask for what you want to see.

The board above is one of those templates, running live. The rest of this guide walks through each step with the same board.

#Step 1: sign in with Google

Go to Sign in and click Continue with Google. There is no separate account or password. The first time you sign in, Widgetry creates a personal organization named after you: that is where your widgets, your designs and your API keys live. If someone already invited you to their organization and you accepted, you can switch between organizations from the menu in the header at any time.

After signing in you land on Widgets, the list of your organization's widgets. It is empty at first.

#Step 2: pick a template and a design

Click New widget, or scroll down to New widget from a template. The gallery shows every widget type running on sample data:

• Filter by type with All, Data, Cards, Animated, SVG and 3D.
• Pick a design with the Gallery design menu. There are 20 built in, plus any your organization has created, and every type works in every design.

You can browse the same templates without signing in at Templates.

When one fits, click Use template. Widgetry copies the template into a new draft widget of your organization and opens the editor. The copy is yours: you can change all of it, and the template never changes afterwards, nor do later edits flow back to it. For this guide, use Board in any design.

#Step 3: edit the widget

The editor has two halves: the parts of the widget on the left, in six tabs, and the preview on the right. Changes save on their own; the header says Saved, Unsaved or Saving.

#Data and schema: what the model fills

Start with Data. Change the board's title, rename a column, add a card. The preview updates as you type. This is the fastest way to see whether the widget suits what you want to show.

The Schema tab is the other half of the same idea. It is a JSON Schema with "type": "object" at the root, and it becomes the input schema of the widget's tool. In a real conversation, the model reads it, gathers the data (from you, from other tools, from files) and calls the tool with an object that matches it. The widget never fetches data on its own. If you add a field to the markup, add it to the schema too, with a description, so the model knows to send it.

While the widget is a draft, the editor accepts broken JSON or data that does not match the schema, so you can edit freely. Problems show in a list under the editor, and a red dot marks the Data or Schema tab.

#Markup, styles and script: how it looks

You do not need these tabs to get a working widget, but they are fully open.

• Markup is Liquid: {{ title }} renders a value and {% for %} repeats. Values are escaped by default, because a model writes the data. Elements can declare host actions without JavaScript: data-wg-message posts a message to the chat, data-wg-link opens a link and data-wg-tool with data-wg-args calls a server tool. Each card of the board sends a message when clicked; in the editor, a notice tells you what it would send.
• Styles read only the --wg-* tokens and the .wg-panel class, so the widget follows whichever design you choose. To fine-tune one design, write rules under :root[data-design="…"].
• Script is for what markup cannot do: timers, canvas, WebGL, timeline animation. It registers with widgetry.onRender and may import only libraries from a closed catalog (three.js, GSAP, d3 and Chart.js), which you tick under Script libraries in Settings. They load from jsDelivr at a pinned version, and the widget declares that origin in its CSP.

#Settings: name, description and image domains

In Settings, the Description for the agent matters most. The model reads it to decide when to use the widget, so say what it shows and what data it is for. Templates come with one; rewrite it for your case.

If your data brings photos from another site, list that site's origin under Image domains, one per line (for example https://images.example.com), up to ten. Hosts block images from any domain the widget does not declare, and the preview blocks them too, so a photo that shows here will show in the chat.

#The preview is a real host

The preview is not a mockup. It loads the same widget document a chat host loads and speaks the MCP Apps protocol with it, inside a chat turn: your request, the tool call (Used show_board) and the widget. Switch between Light and Dark to check both themes, and change the design with Widget design without leaving the editor. View or duplicate this design opens it in the designer.

#Step 4: publish

Click Publish in the header. Publishing checks three things:

1. The data schema is valid.
2. The sample data satisfies it.
3. The widget has a description.

If something fails, the editor says Can't publish: fix what's marked below. and lists it.

Once published, the widget is part of your organization's MCP endpoint as a tool named show_<slug> (the slug is set from the template's name when the widget is created, and stays the same if you rename it; the board becomes show_board), with its ui:// resource. From then on, Widgetry refuses an edit that would break the schema or the data, so the live tool never breaks under a conversation. Unpublish takes it off the endpoint again.

#Step 5: take it to the chat

Below the preview, the editor shows both ways out.

#Try it on Widgetry's MCP endpoint

The quickest way to see the widget in a real conversation is to connect Widgetry's own endpoint, https://widgets.gonzaloverdugo.com/mcp, as an MCP connector or server in your agent. Chat apps that connect with OAuth (claude.ai, ChatGPT and others) send you to Widgetry to sign in and choose the organization; coding agents (Claude Code, Codex and others) use an API key in the Authorization: Bearer header. Every published widget appears as a tool; drafts do not. Then ask for what you want to see, for example "show my open tasks as a board", and the agent gathers the data and shows the widget. The full setup for each client is in Connect Widgetry to your agent.

#Link it from your own MCP server

Take it to your MCP server is the main way out: the widget works next to your own tools and data. It has two modes:

• Link to Widgetry: your server reads the published widget from its live URL with a read-only key (an owner creates it in Settings), so what you publish later reaches it without a deploy.
• Download the files: you get <slug>.html and <slug>.widget.json and your server does not depend on Widgetry.

Each mode shows the install command and the registration code for the official MCP Apps SDK, ready to copy. Add an interactive UI to your MCP server explains that code line by line.

#Working as a team

Widgets, designs and keys belong to an organization, and a person can belong to several. Each member has a role:

To invite someone, an owner opens Settings, Invitations, writes their Google email, picks a role and clicks Invite. Widgetry does not send emails yet: copy the link it shows and send it yourself. It expires in seven days, and only the Google account with that email can accept it.

API keys live in Settings, API keys. Owners create them with Read or Read and write permission; a key is shown once, so copy it then. A read key serves the MCP endpoint and linked widgets. A write key also lets an agent or a script create, edit and publish widgets. To start another organization, use New organization in the same page.

#Next steps

• Give your widgets your own look: Create your own design.
• Let your agent do the editing for you through Widgetry's MCP tools: Create MCP Apps widgets with an AI agent.
• Browse every widget type with its sample data: Templates.