Components
The Quickstart uses the simplest entry point: your own chip, linked to a route on your server that sends the user to Configure's page. Use the components below when you want Configure's page inside yours instead, or, in a chat, Configure's card in the thread. Configure serves them all, and all of them run in production. Two scripts carry them: https://configure.dev/js/configure.js gives you the Configure.* functions, and https://configure.dev/components/configure-components.global.js defines the raw elements. Include each once per page.
publishableKey is your pk_ key, safe in the browser, and agent is your agent handle. Both come from npx configure setup --users. displayName is what the user reads; agent is the identity every approval and token is bound to.
Composer button
The entry point for a chat. It sits next to the image and file attachments as a + menu, with a Personalization row that opens Configure's hosted flow inline. Pass linkEl so the flow mounts in a dismissible panel across the assistant lane instead of inside the composer row.
html
<script src="https://configure.dev/js/configure.js"></script>
<div id="configure-entry"></div>
<div id="configure-link-host"></div>
<script>
Configure.personalizationButton({
el: "#configure-entry",
linkEl: "#configure-link-host",
publishableKey: "pk_...",
agent: "your-agent",
displayName: "Your App",
theme: "light", // or "dark"; omit it and the script warns and follows the system
onImage: () => openImagePicker(),
onFile: () => openFilePicker(),
});
</script>Let the link host span the assistant message lane. Do not cap it at 420px; the flow needs the width.
Your own button
Most products already have a button style, so the entry point is your own control. It links to the route that sends the user to Configure's page, and Configure brings them back to your return route. This is the Quickstart pattern, steps 2 through 5.

html
<a class="chip" href="/configure/start">Connect</a>The route mints the link with a returnUrl and redirects. profileFor is the handle from the Quickstart, and RETURN_URL is your return route's https address, a constant:
ts
const RETURN_URL = "https://yourapp.com/configure/return";
app.get("/configure/start", async (req, res) => {
const connect = await profileFor(req.user.id).connect({ returnUrl: RETURN_URL });
res.redirect(connect.connect_url!); // always set on a minted link; Configure's page, then back to RETURN_URL
});Configure brings the user back to your return route: Quickstart, step 5.
Ways in for existing users
People who signed up before you added Configure never see your onboarding step. Ask them to connect when they sign in, and keep a strip above your composer and a row in your sidebar until they connect. None of these is a Configure component. Build them in your app and point them at the same start route as your own button. Existing users has the rule for when to ask.

Integration button
For a settings or integrations surface, the raw element renders a connect or manage control that opens Configure's hosted flow itself.
html
<script src="https://configure.dev/js/configure.js"></script>
<script src="https://configure.dev/components/configure-components.global.js"></script>
<configure-personalization-button
variant="integration"
api-key="pk_..."
agent="your-agent"
external-id="user_123"
></configure-personalization-button>variant is menu, the composer button above as a raw element, or integration. With manual the element announces its events and never opens the flow, which is how the demos on this page run.
Hosted link
When you want the flow on its own, mount it and take the token from the event. This is the same grant the composer button and the integration button run; here your page owns where it renders.
html
<script src="https://configure.dev/js/configure.js"></script>
<div id="configure-link"></div>
<script>
Configure.link({
el: "#configure-link",
publishableKey: "pk_...",
agent: "your-agent",
displayName: "Your App",
theme: "light",
onEvent: (event) => {
if (event.type === "configure:linked") {
// event.payload = { token, userId, tokenUse }
sendTokenToYourBackend(event.payload.token);
}
},
});
</script>Configure.link() returns a frame handle, not the token. The token arrives in configure:linked, through onEvent or as a DOM CustomEvent on the mount element. Send it to your server and use it there with configure.profile({ token }).
Connected
The composer button flips its own state when it sees the link complete on the page. Across reloads, and for your own button, render the connected state from what your server already knows: the context it stored.
ts
// Quickstart step 6 stores { text, refreshedAt } and the webhook keeps it current. text is null until the user connects.
const stored = await store.get(user.id);
const label = stored?.text ? "Connected" : "Connect";Render from what Configure told you, stored and kept current by the webhook. That keeps page loads off the network. Never set a "connected" flag from your own events.
Once the user is connected, use the same stored context to greet them and suggest what to do next: Personalization.
Card
In a chat, Configure's card lets the user connect without leaving the conversation. The card is an MCP app: a page Configure serves and your page hosts in an iframe. Everything inside it, the marks, the text, and the Connect and Not now buttons, is Configure's, and the page around it cannot restyle or reword it. Its Connect button opens the same hosted flow.

Load Configure's host script once per page:
html
<script src="https://api.configure.dev/mcp-apps/configure-mcp-host.js"></script>When the user asks your AI
A user tells your agent "Hey, I want to connect my Gmail". The model calls configure_connect with app: "gmail". The tool is in profile.tools() and on the MCP session (Quickstart, step 7). Show its result in the thread as the card:
js
// Where your chat renders tool results.
if (toolCall.name === "configure_connect") {
ConfigureMcpAppHost.mount({
container: el, // the tool result's spot in the thread
resourceUri: "ui://configure/connect/v9.html", // over MCP, the tool's _meta.ui.resourceUri
result: toolResult, // the tool result, exactly as returned
agentName: "Your App", // becomes the card title
});
}result takes either shape: what profile.executeTool() returns, or the MCP tool result with its structuredContent. If the card cannot mount, the same call shows a plain link to the same page.
When your page asks
You can also mint the result yourself, for example when the user clicks your chip in a chat. profileFor is the handle from the Quickstart:
ts
const connect = await profileFor(user.id).connect(); // hand this to the page, unchangedjs
ConfigureMcpAppHost.mount({
container: el, // where the card renders in the thread
resourceUri: "ui://configure/connect/v9.html",
result: connect, // the connect() result, exactly as returned
agentName: "Your App", // becomes the card title
});The host script owns the iframe, sizes it, passes the theme in, and opens the card's link in a new tab. mount() also accepts theme: "light" | "dark", onOpenLink(url) to open the link yourself, and onTeardown(), which runs when the card is removed. It returns a handle with element, iframe, dispose() and setTheme(). Call dispose() when your component unmounts, or a single-page app leaves the iframe behind. Call setTheme() when your app's theme changes, because the card reads the theme once at mount.
Any resourceUri of the form ui://configure/connect/v<number>.html serves the current card, so a URI you stored keeps working when the card changes. The link inside the card is minted per user and expires at expires_at, so mint a new result when the user asks again.
Approval card
For the two tools that change the outside world, sending an email and creating an event, the bundle ships a card that asks the user first. It shows the tool and its parameters, times out to Deny, and answers with one event.
html
<configure-tool-approval
action-id="call_123"
tool="configure_email_send"
timeout-seconds="60"
></configure-tool-approval>
<script>
const card = document.querySelector("configure-tool-approval");
card.params = { to: "sam@example.com", subject: "Intro" }; // a property, not an attribute
card.addEventListener("configure:tool-approve", (e) => runTool(e.detail.actionId));
card.addEventListener("configure:tool-deny", (e) => skipTool(e.detail.actionId));
card.addEventListener("configure:tool-always-allow", (e) => {
rememberAlwaysAllow(card.tool); // yours: stop asking for this tool
runTool(e.detail.actionId); // it also approves this call
});
</script>Always allow sends only configure:tool-always-allow, not configure:tool-approve, so run the tool there too. Remembering the choice is yours.
Attributes
On the raw <configure-personalization-button>:
| Attribute | Default | What it does |
|---|---|---|
api-key | Your pk_ key. Required: without it the element shows a notice asking for one | |
agent | Your agent handle | |
variant | menu | menu or integration |
external-id | Your user id, so the connection lands on the context your server reads | |
connectors | gmail,calendar,drive,notion,sheets | Which apps the flow offers, comma separated |
personalization-label | Personalization | The text of the Personalization row |
placeholder | Ask anything | Placeholder text in the composer slot |
manual | false | Announce events only; never open the flow |
hide-images, hide-files | false | Remove the image or file rows from the + menu |
image-label, file-label | Images, Files | Text of the image and file rows |
Events the element announces: configure:personalization-open as the flow opens, configure:personalization-toggle when the Personalization switch changes, with detail.enabled (true once the user links), configure:personalization-menu-toggle for the + menu, and configure:image-select and configure:file-select for the attachment rows.
The element does not announce configure:linked. configure.js runs the flow for it and dispatches configure:linked on document, with the token in event.detail, as in Hosted link.
The buttons are real buttons: keyboard reachable, with a visible focus ring.