The HTML component is the one part of an MCP App you write yourself: your own HTML, CSS and JavaScript, for a fully branded part of the app. It runs in a sandbox, and talks to the app through one object, window.qatom.

Add it from the designer’s Components, under Custom. Its settings are:

Setting Field What it is
Code html Your HTML, with any <style> and <script>. Up to 96 KB
Hosts hosts Up to 10 https hosts your code may load from or call, such as cdn.example.com
Starting height height Its height in pixels until your code sizes it: 40 to 2000. Defaults to 160
Name label A name for screen readers, such as “Seat map”

The sandbox

Your code runs in its own frame, sandboxed to scripts only. It has a unique origin, so:

What Allowed
Inline <script> and <style> Yes
Scripts, styles, fonts, images, media and fetch/WebSocket From your listed https hosts only
Images, fonts and media as data: (and images and media as blob:) Yes
Other frames, workers, plugins, <base>, form posts No

A host must be a domain name over https, with an optional *. in front. IP addresses, ports, paths and http are refused.

window.qatom

Before your HTML runs, the frame defines window.qatom. It has one property and three methods.

values

The moment’s values, or null until they arrive. They arrive just after your frame loads, so read them with onValues rather than at the top of your script.

{
  state: "offer", // "offer", "delivered" or "failed"
  item: {
    name: "Weather Now",
    description: "Current conditions",
    price: "$0.250",
    seller: "Example Co"
  },
  input: { city: "Lisbon" }, // the buyer's inputs
  result: undefined, // the answer, once "delivered"
  preview: false // true in the dashboard's designer
}
Field Type What it is
state "offer", "delivered" or "failed" Which moment is being drawn
item object The item’s name, description, price (formatted) and seller
input object The buyer’s inputs, by name
result any Your endpoint’s answer, as it sent it. Present only when state is "delivered"
preview boolean true while you design or preview the app in the dashboard, with sample values

values is read-only and is a copy: changing it changes nothing in the app.

onValues(fn)

Calls fn(values) when the values arrive, and at once if they already have. Register it at the top of your script.

<div id="greeting"></div>
<script>
  window.qatom.onValues(function (v) {
    var delivered = v.state === "delivered" && v.result;
    var name = delivered ? v.result.title : v.item.name;
    document.getElementById("greeting").textContent = name;
  });
</script>

Write values into the page with textContent, not innerHTML: they include what the buyer typed and what your endpoint answered.

openLink(url)

Asks the chat to open url in the buyer’s browser, outside the chat. Only http and https addresses are opened. Call it from a click; it does nothing in the designer.

<button id="track">Track my order</button>
<script>
  var track = document.getElementById("track");
  track.addEventListener("click", function () {
    var v = window.qatom.values;
    var url = v && v.result && v.result.tracking_url;
    if (url) window.qatom.openLink(url);
  });
</script>

A plain <a href> does nothing inside the sandbox; use openLink.

resize()

Measures your page’s <body> and asks for that height (kept between 40 and 2000 pixels). It takes no argument.

You rarely need to call it: the frame resizes itself when it loads, whenever the body changes size, and after the values arrive. Call it after a change the body’s size does not show, such as an image you load later.

img.addEventListener("load", function () {
  window.qatom.resize();
});

A complete example

<style>
  body { margin: 0; font: 15px/1.5 system-ui, sans-serif; }
  .banner {
    padding: 16px;
    border-radius: 12px;
    background: #0f2a2e;
    color: #e8f6f3;
  }
  .banner h2 { margin: 0 0 4px; font-size: 18px; }
  .banner button {
    margin-top: 12px;
    padding: 8px 14px;
    border: 0;
    border-radius: 8px;
    cursor: pointer;
  }
</style>
<div class="banner">
  <h2 id="title"></h2>
  <p id="line"></p>
  <button id="open" hidden>See your forecast</button>
</div>
<script>
  window.qatom.onValues(function (v) {
    var line = document.getElementById("line");
    var open = document.getElementById("open");
    document.getElementById("title").textContent = v.item.name;
    if (v.state === "delivered" && v.result) {
      line.textContent =
        "High of " + v.result.high + "°C in " + v.input.city + ".";
      open.hidden = !v.result.url;
      open.onclick = function () {
        window.qatom.openLink(v.result.url);
      };
    } else {
      line.textContent =
        "Your forecast for " + v.input.city + " shows here once you approve.";
    }
  });
</script>

In the designer

Limits