Specification Overview

MCPlet Specification v202603-03

This page is an HTML overview for fast reading and search indexing. The normative draft remains the raw markdown source, but this overview surfaces the major concepts, contracts, and security model in a crawler-friendly format.

Status Draft
Version v202603-03
Draft date 2026-03-27
Profiles WebUI and Agent
Maintained by MCPlet Working Group
Canonical source Raw markdown draft

Purpose and scope

MCPlet defines constrained, AI-first capability units with one business intent, one primary MCP tool contract, optional MCP Apps UI, explicit model-versus-app safety boundaries, and host-managed orchestration.

The goal is predictable, reviewable, and secure AI-tool interaction. MCPlet is a convention profile on top of MCP and MCP Apps; it does not redefine transport, runtime, sandboxing, or backend architecture.

Host profiles

MCPlet currently supports two host implementation profiles.

  • WebUI Profile: an MCP client or agent shell that renders MCP Apps UI, invokes tools, and manages visibility and safety in a user-facing environment.
  • Agent Profile: an orchestration layer composed of specialized agents and an externally configured LLM, with no required general-purpose UI layer.

Both profiles keep MCPlets stateless by default. State, conversation context, and policy enforcement remain host responsibilities.

How MCPlet compares to MCP and MCP Apps

MCPlet is easiest to understand when treated as a layer on top of existing standards rather than as a replacement for them.

Layer Primary role Defines Does not define
MCP Protocol layer Tool and resource transport, discovery, and invocation contracts. Intent modeling, action safety policy, or opinionated classification rules.
MCP Apps UI integration layer Host-view rendering, iframe lifecycle, and app bridge behavior. Business intent boundaries, tool classification, or host security conventions.
MCPlet Convention profile Single-intent units, read/prepare/action classification, visibility rules, auth requirements, and host-managed safety boundaries. MCP transport, generic runtime behavior, or a mandatory frontend framework.

read

Side-effect free and idempotent. Suitable for autonomous invocation when the host allows model visibility.

prepare

Gathers or validates information before commitment. Useful as an explicit checkpoint in multi-step workflows.

action

Causes irreversible side effects. Requires stronger confirmation and enforcement, especially when visible to the model.

Code-first metadata contract

MCPlet v202603-03 is explicitly code-first. Hosts discover MCPlet semantics through registration metadata such as _meta.mcpletType, _meta.visibility, _meta.auth, _meta.ui, and optional _meta.pool.

{
  "_meta": {
    "mcpletType": "action",
    "visibility": ["model", "app"],
    "mcpletToolResultSchemaUri": "mcplet://tool-result-schema/approve_order",
    "ui": {
      "resourceUri": "ui://orders/approve.html",
      "displayMode": "inline"
    },
    "auth": {
      "required": "passkey",
      "enforcement": "strict",
      "promptMessage": "Please authenticate with Passkey to confirm"
    }
  }
}

mcplet.yaml can still exist for backward-compatibility defaults, but it is not the single source of truth once code metadata is present.

Passkey enforcement and protected actions

Protected MCPlets declare authentication in _meta.auth. For model-visible action tools, the host intercepts the call, obtains a Passkey assertion through a browser context, injects the verification payload outside the business arguments, and the MCPlet backend verifies that assertion before any irreversible action executes.

This separation matters because it keeps the LLM focused on business inputs while moving cryptographic confirmation into host-controlled and backend-verifiable paths.

Pools, agents, and routing boundaries

MCPlet v202603-03 introduces named Pools and accessible Pool lists for agents. Pools let hosts group MCPlets by target system or policy scope, while per-agent Pool grants enforce least-privilege access during dispatch.

The Agent Profile also distinguishes between an internal A2A local protocol bus and an external A2A protocol endpoint for external agents. Hosts remain responsible for authentication, policy, and dispatch validation.

Read the full draft

The raw markdown file remains the normative draft source. Use the HTML overview for fast scanning, the FAQ for short answers, and the patent notice for licensing context.

Open getting started guide Open raw markdown Browse FAQ

Need licensing context? Review the intellectual property notice.