Getting Started

First steps for MCPlet hosts and tool authors

This guide compresses MCPlet v202603-03 into an implementation path: choose the right host profile, classify tools correctly, expose code-first metadata, and apply stronger enforcement where actions can cause side effects.

Version v202603-03
Maintained by MCPlet Working Group
Normative source Raw markdown draft
Updated 2026-04-01

Implementation path

  1. Choose whether your host is WebUI Profile or Agent Profile. This determines whether MCP Apps rendering is part of your runtime and how confirmation flows are implemented.
  2. Classify each tool as read, prepare, or action. This is not documentation only; it is part of the safety model.
  3. Register code-first metadata in _meta, including mcpletType, visibility, and optional ui, auth, and pool fields.
  4. Expose a tool-result schema URI so the host can validate structured results and downstream consumers can reason about outputs safely.
  5. Require strict passkey enforcement when a model-visible action can trigger irreversible side effects.
If you only remember one rule: never treat MCPlet as a replacement for MCP. MCP is the protocol layer; MCPlet is the convention layer that narrows tool behavior into safer, reviewable units.

1. Choose the host profile

Use WebUI Profile if you render MCP Apps UI. Use Agent Profile if your host is an orchestration layer of specialized agents with an externally configured LLM.

2. Classify the tool

Pick read for safe retrieval, prepare for staged validation, and action for irreversible side effects that need tighter control.

3. Expose code-first metadata

At minimum, declare _meta.mcpletType and _meta.visibility. Add result schema URIs, UI metadata, auth metadata, and pools where applicable.

4. Protect model-visible actions

If an action is visible to the model, require explicit interception and strong confirmation, preferably with strict Passkey enforcement.

MCP, MCP Apps, and MCPlet at a glance

Layer Primary role What it gives you What it does not give you
MCP Protocol Tool and resource transport, discovery, and invocation semantics. Intent modeling, action safety policy, or opinionated tool classification.
MCP Apps UI integration Host-view rendering, iframe lifecycle, and app bridge behavior. Business intent boundaries, metadata safety rules, or auth conventions.
MCPlet Convention profile Single-intent units, read/prepare/action classification, visibility constraints, auth requirements, and host-managed safety boundaries. MCP transport, generic runtime behavior, or a mandatory frontend framework.

Minimal code-first metadata example

This example shows the fields most implementations should think about first when mapping a tool into MCPlet.

{
  "_meta": {
    "mcpletType": "prepare",
    "visibility": ["model", "app"],
    "mcpletToolResultSchemaUri": "mcplet://tool-result-schema/check_order",
    "ui": {
      "resourceUri": "ui://orders/check.html",
      "displayMode": "inline"
    }
  }
}

For irreversible operations, switch the classification to action and add _meta.auth with stricter enforcement.

When to use MCPlet and when not to

Use MCPlet when

  1. You want one reviewable business intent per tool.
  2. You need the host to enforce clear model-versus-app boundaries.
  3. You want a code-first metadata contract on top of MCP.

Do not use MCPlet when

  1. Your tool surface is intentionally broad and multi-purpose.
  2. You are looking for a replacement protocol instead of a convention profile.
  3. Your host cannot manage state, interception, or safety policy.
Read HTML overview Browse FAQ Open raw markdown

Need licensing context? Review the intellectual property notice.