Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt

Use this file to discover all available pages before exploring further.

An Interactive Tool is a Type backed by a layout component. The AI calls it with structured JSON; the platform validates against the schema, compiles to BindJS, and returns a rendered UI bundle. This guide walks through building one end-to-end.

​
Prerequisites

​
1. Author a layout component

A layout component is the BindJS code that:
  • Declares the tool’s input schema (via properties).
  • Defines what the AI is allowed to render (via component allowlists).
  • Renders the validated input as a layout.
A minimal layout component: 
const properties = {
  title: {
    type: "string",
    title: "Title",
    description: "Main heading",
    inspector: { control: "singleline", placeholder: "Lounge Chair" }
  },
  price: {
    type: "string",
    title: "Price",
    inspector: { control: "singleline", placeholder: "$128.99" }
  },
  description: {
    type: "string",
    title: "Description",
    inspector: { control: "multiline", numberOfLines: 4 }
  }
} satisfies ComponentProperties;

const body = (props: InferProps<typeof properties>): Component => {
  return VStack({ spacing: 16, alignment: "leading" }, [
    Text(props.title).font("title2").fontWeight("bold"),
    Text(props.price).foregroundStyle(Color("#7A7A7A")),
    Text(props.description).font("body")
  ])
    .padding(24)
    .background(Color("white"))
    .cornerRadius(12);
};

export default defineComponent({
  metadata: {
    title: "Product Detail",
    description: "Image, title, price, and description"
  },
  properties,
  body
});
For the property schema language and the BindJS layout primitives, see the BindJS Reference.

​
Add a previews array

Previews are sample inputs that MCP App Studio uses to render the component without an AI call. Always include at least one — it’s how you’ll test changes. 
const previews = [
  Self({
    title: "Lounge Chair",
    price: "$128.99",
    description: "A generous, hand-finished blanket woven from merino wool and alpaca."
  })
    .previewName("With description")
];

export default defineComponent({
  metadata,
  properties,
  body,
  previews
});

​
2. Create a Type that points at the component

A Type registers the component with the MCP server. In MCP App Studio:
  1. Open UI Tools in the project sidebar and click + to add one.
  2. Select the layout component you just authored.
  3. Set the Type’s name (becomes the slug, the MCP tool name) and description (becomes the LLM-facing tool description).
  4. Save.
The Type’s input schema is auto-generated from the component’s properties. The Type’s name slugifies to lowercase-underscore — Product Detail → product_detail. The slug is immutable after first publish.
The Interactive Tool edit page in MCP App Studio with Tool Name, Title, Description, and Component fields visible

​
3. Configure allowed components (for layouts that compose children)

If your layout accepts children — for example, a layout that renders a list of arbitrary product cards — declare the allowed children on the property: 
properties: {
  components: {
    type: "array",
    title: "Components",
    description: "Components rendered in the body",
    allowedComponents: ["ProductCard", "ProductCarousel", "ProductComparison"],
    minItems: 1
  }
}
The AI can only compose the listed components inside components. Any other reference is rejected during schema validation. See Component allowlists.

​
4. Test the tool inline

In MCP App Studio, click the Type. The center pane shows a live preview; the right pane is the test panel.
  1. Fill the test inputs (or use the defaults from your previews array).
  2. Click Run.
  3. The platform validates your input against the schema, compiles BindJS, resolves the package, and renders the result.
This is the same code path that runs when an AI calls the tool from a connected MCP host.
The product_detail Interactive Tool tested inside MCP App Studio — a live Lounge Chair preview on the left and a populated test panel on the right

​
5. Iterate and refine

A few common refinements once the basic tool works:
  • Tighten the description. The Type’s description is the tool’s MCP description — what the AI reads when deciding whether to call it. Make it specific: “Render a single product detail card. Use when the user wants to view one product in depth, not when comparing multiple products.”
  • Add validation to properties. minLength, maxLength, min, max, pattern. Schema violations return clear errors to the AI on retry.
  • Constrain allowed components tightly. The smaller the allowlist, the more predictable the AI’s output.
  • Update the project Instructions to reference the new tool and describe when it should be used. See Project setup.

​
6. Publish

Once the tool works on the draft endpoint, publish the server to promote it to production.

Authoring BindJS components

Component primitives, modifiers, and the inspector schema.

Component allowlists

Constrain what the AI can render.

Testing tools in MCP App Studio

The test panel, preview gallery, and live device preview.

Tools and Types

Conceptual: how Types become MCP tools.