Skip to content

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.

An app's home page with the chip circled in red: it reads Connect, followed by the marks of four AI assistants

A chip under the composer on an app's home page.
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.

A composer with a blue strip joined to its top: the marks of four AI assistants, the line Bring what your AI already knows about you, and a Connect button

A strip above the composer, for a user who has not connected.

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.

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.

A chat where the user writes Hey, I want to connect my Gmail, and Configure's card appears below it, titled Configure Remy, reading Connect your accounts, with a Connect button and Not now

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, unchanged
js
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>:

AttributeDefaultWhat it does
api-keyYour pk_ key. Required: without it the element shows a notice asking for one
agentYour agent handle
variantmenumenu or integration
external-idYour user id, so the connection lands on the context your server reads
connectorsgmail,calendar,drive,notion,sheetsWhich apps the flow offers, comma separated
personalization-labelPersonalizationThe text of the Personalization row
placeholderAsk anythingPlaceholder text in the composer slot
manualfalseAnnounce events only; never open the flow
hide-images, hide-filesfalseRemove the image or file rows from the + menu
image-label, file-labelImages, FilesText 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.

Infrastructure to connect agents, apps, and chats