@modelcontextprotocol/ext-apps - v0.0.1
    Preparing search index...

    Class PostMessageTransport

    JSON-RPC transport using window.postMessage for iframe↔parent communication.

    This transport enables bidirectional communication between MCP Apps running in iframes and their host applications using the browser's postMessage API. It implements the MCP SDK's Transport interface.

    The eventSource parameter provides origin validation by filtering messages from specific sources. Guest UIs typically don't need to specify this (they only communicate with their parent), but hosts should validate the iframe source for security.

    Guest UI (default):

    const transport = new PostMessageTransport(window.parent);
    await app.connect(transport);

    Host (with source validation):

    const iframe = document.getElementById('app-iframe') as HTMLIFrameElement;
    const transport = new PostMessageTransport(
      iframe.contentWindow!,
      iframe.contentWindow  // Validate messages from this iframe only
    );
    await bridge.connect(transport);

    Implements

    • Transport
    Index

    Constructors

    constructor

    Properties

    onclose? onerror? onmessage? sessionId? setProtocolVersion?

    Methods

    close send start

    Constructors

    • Create a new PostMessageTransport.

      Parameters

      • eventTarget: Window = window.parent

        Target window to send messages to (default: window.parent)

      • OptionaleventSource: MessageEventSource

        Optional source validation. If specified, only messages from this source will be accepted. Guest UIs typically don't need this (they only receive from parent), but hosts should validate the iframe source.

      Returns PostMessageTransport

      const transport = new PostMessageTransport(window.parent);

      const iframe = document.getElementById('app') as HTMLIFrameElement;
      const transport = new PostMessageTransport(
        iframe.contentWindow!,
        iframe.contentWindow  // Only accept messages from this iframe
      );

    Properties

    onclose?: () => void

    Called when the transport is closed.

    Set this handler to be notified when close is called.

    onerror?: (error: Error) => void

    Called when a message parsing error occurs.

    This handler is invoked when a received message fails JSON-RPC schema validation. The error parameter contains details about the validation failure.

    Type Declaration

      • (error: Error): void

      • Parameters

        • error: Error

          Error describing the validation failure

        Returns void

    onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void

    Called when a valid JSON-RPC message is received.

    This handler is invoked after message validation succeeds. The start method must be called before messages will be received.

    Type Declaration

      • (message: JSONRPCMessage, extra?: MessageExtraInfo): void

      • Parameters

        • message: JSONRPCMessage

          The validated JSON-RPC message

        • Optionalextra: MessageExtraInfo

          Optional metadata about the message (unused in this transport)

        Returns void

    sessionId?: string

    Optional session identifier for this transport connection.

    Set by the MCP SDK to track the connection session. Not required for PostMessageTransport functionality.

    setProtocolVersion?: (version: string) => void

    Callback to set the negotiated protocol version.

    The MCP SDK calls this during initialization to communicate the protocol version negotiated with the peer.

    Type Declaration

      • (version: string): void

      • Parameters

        • version: string

          The negotiated protocol version string

        Returns void

    Methods

    • Stop listening for messages and cleanup.

      Removes the message event listener and calls the onclose callback if set.

      Returns Promise<void>

    • Send a JSON-RPC message to the target window.

      Messages are sent using postMessage with "*" origin, meaning they are visible to all frames. The receiver should validate the message source for security.

      Parameters

      • message: JSONRPCMessage

        JSON-RPC message to send

      • Optionaloptions: TransportSendOptions

        Optional send options (currently unused)

      Returns Promise<void>

    • Begin listening for messages from the event source.

      Registers a message event listener on the window. Must be called before messages can be received.

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    SecurityUsage
    Constructors
    Properties
    Methods