MCP Apps Kit - v0.5.0
    Preparing search index...

    Interface AppsClient<T>

    Unified client interface for UI code

    interface AppsClient<T extends ToolDefs = ToolDefs> {
        hostContext: HostContext;
        toolInput?: Record<string, unknown>;
        toolMeta?: Record<string, unknown>;
        toolOutput?: Record<string, unknown>;
        tools: ToolMethods<T>;
        callTool<K extends string | number | symbol>(
            name: K,
            args: InferToolInputs<T>[K],
        ): Promise<InferToolOutputs<T>[K]>;
        getFileDownloadUrl?(fileId: string): Promise<{ downloadUrl: string }>;
        getHostCapabilities(): HostCapabilities;
        getHostVersion(): HostVersion;
        getState<S>(): S;
        log(level: "error" | "debug" | "info" | "warning", data: unknown): void;
        notifyIntrinsicHeight?(height: number): void;
        onHostContextChange(handler: (context: HostContext) => void): () => void;
        onTeardown(handler: (reason?: string) => void): () => void;
        onToolCancelled(handler: (reason?: string) => void): () => void;
        onToolInput(handler: (input: Record<string, unknown>) => void): () => void;
        onToolInputPartial(
            handler: (input: Record<string, unknown>) => void,
        ): () => void;
        onToolResult(handler: (result: ToolResult<T>) => void): () => void;
        openLink(url: string): Promise<void>;
        readResource(uri: string): Promise<{ contents: ResourceContent[] }>;
        requestClose(): void;
        requestDisplayMode(
            mode: "inline" | "fullscreen" | "pip",
        ): Promise<{ mode: string }>;
        requestModal?(options: ModalOptions): Promise<ModalResult>;
        sendFollowUpMessage(prompt: string): Promise<void>;
        sendLog(
            level:
                | "error"
                | "debug"
                | "info"
                | "warning"
                | "notice"
                | "critical"
                | "alert"
                | "emergency",
            data: unknown,
        ): Promise<void>;
        sendMessage(content: { text: string; type: "text" }): Promise<void>;
        sendSizeChanged(params: SizeChangedParams): Promise<void>;
        setCallToolHandler(handler: CallToolHandler): void;
        setListToolsHandler(handler: ListToolsHandler): void;
        setState<S>(state: S): void;
        setupSizeChangedNotifications(): () => void;
        updateModelContext(params: UpdateModelContextParams): Promise<void>;
        uploadFile?(file: File): Promise<{ fileId: string }>;
    }

    Type Parameters

    • T extends ToolDefs = ToolDefs
    Index

    Properties

    hostContext toolInput? toolMeta? toolOutput? tools

    Methods

    callTool getFileDownloadUrl? getHostCapabilities getHostVersion getState log notifyIntrinsicHeight? onHostContextChange onTeardown onToolCancelled onToolInput onToolInputPartial onToolResult openLink readResource requestClose requestDisplayMode requestModal? sendFollowUpMessage sendLog sendMessage sendSizeChanged setCallToolHandler setListToolsHandler setState setupSizeChangedNotifications updateModelContext uploadFile?

    Properties

    hostContext: HostContext

    Current host context

    toolInput?: Record<string, unknown>

    Current tool input (if any)

    toolMeta?: Record<string, unknown>

    Current tool metadata (if any)

    toolOutput?: Record<string, unknown>

    Current tool output (if any)

    tools: ToolMethods<T>

    Typed tool methods object.

    Provides direct method access to tools with the naming convention call{ToolName}. This is an alternative to using callTool() that provides a more ergonomic API.

    // Instead of:
    await client.callTool("greet", { name: "Alice" });

    // You can use:
    await client.tools.callGreet({ name: "Alice" });

    Methods

    • Call a server tool with typed arguments

      Type Parameters

      • K extends string | number | symbol

      Parameters

      • name: K

        Tool name (must be a key in T)

      • args: InferToolInputs<T>[K]

        Tool arguments (typed from input schema)

      Returns Promise<InferToolOutputs<T>[K]>

      Tool result (typed from output schema)

    • Get file download URL (ChatGPT only)

      Parameters

      • fileId: string

        File ID from uploadFile

      Returns Promise<{ downloadUrl: string }>

      Download URL

      Error on unsupported platforms

    • Get host capabilities

      Returns the capabilities advertised by the host during handshake. Use this to check if features like logging or server tools are supported.

      Returns HostCapabilities

      Host capabilities or undefined if not yet connected

    • Get host version information

      Returns the name and version of the host application.

      Returns HostVersion

      Host version info or undefined if not yet connected

    • Get persisted widget state On ChatGPT: Returns session-scoped state On MCP Apps: Returns null (silent no-op)

      Type Parameters

      • S

      Returns S

      State or null if not set

    • Log to host console

      Parameters

      • level: "error" | "debug" | "info" | "warning"

        Log level

      • data: unknown

        Data to log

      Returns void

    • Notify host of widget's intrinsic height (ChatGPT only)

      Call this when your widget's content height changes to prevent scroll clipping. The host will adjust the container accordingly.

      Parameters

      • height: number

        Widget height in pixels

      Returns void

    • Subscribe to host context changes

      Parameters

      • handler: (context: HostContext) => void

        Callback for context changes

      Returns () => void

      Unsubscribe function

    • Subscribe to teardown events

      Parameters

      • handler: (reason?: string) => void

        Callback for teardown

      Returns () => void

      Unsubscribe function

    • Subscribe to tool cancellation

      Parameters

      • handler: (reason?: string) => void

        Callback for cancellation

      Returns () => void

      Unsubscribe function

    • Subscribe to tool input changes

      Parameters

      • handler: (input: Record<string, unknown>) => void

        Callback for tool input

      Returns () => void

      Unsubscribe function

    • Subscribe to partial/streaming tool input

      Called when the host sends partial tool arguments during streaming. Useful for showing real-time input as the user types or as the model generates.

      Parameters

      • handler: (input: Record<string, unknown>) => void

        Callback for partial input

      Returns () => void

      Unsubscribe function

    • Subscribe to tool results

      Parameters

      • handler: (result: ToolResult<T>) => void

        Callback for tool results

      Returns () => void

      Unsubscribe function

    • Open an external link

      Parameters

      • url: string

        URL to open

      Returns Promise<void>

    • Read an MCP resource

      Parameters

      • uri: string

        Resource URI

      Returns Promise<{ contents: ResourceContent[] }>

      Resource contents

    • Request widget close (ChatGPT only, no-op on MCP Apps)

      Returns void

    • Request a different display mode

      Parameters

      • mode: "inline" | "fullscreen" | "pip"

        Target display mode

      Returns Promise<{ mode: string }>

      Actual mode applied

    • Request a host-owned modal dialog (ChatGPT only)

      Spawns a native ChatGPT modal for confirmations, inputs, etc. Returns the user's response when the modal is dismissed.

      Parameters

      Returns Promise<ModalResult>

      User's modal response

      Error on unsupported platforms

    • Send a follow-up message (convenience alias)

      Parameters

      • prompt: string

        Message text

      Returns Promise<void>

    • Send a log message to the host

      Unlike the log() method which logs to the local console, this sends logs through the MCP protocol to the host for debugging and telemetry purposes.

      Parameters

      • level:
            | "error"
            | "debug"
            | "info"
            | "warning"
            | "notice"
            | "critical"
            | "alert"
            | "emergency"

        Log level

      • data: unknown

        Data to log

      Returns Promise<void>

    • Send a message to the conversation

      Parameters

      • content: { text: string; type: "text" }

        Message content

      Returns Promise<void>

    • Send size changed notification to host

      Notifies the host when the widget's size changes. Use this for manual size reporting.

      Parameters

      • params: SizeChangedParams

        Size parameters

      Returns Promise<void>

    • Set handler for tool calls from the host

      When the host calls a tool exposed by this app, this handler will be invoked with the tool name and arguments.

      Parameters

      • handler: CallToolHandler

        Handler function for tool calls

      Returns void

    • Set handler for listing app-exposed tools

      When the host requests the list of tools this app exposes, this handler will be invoked.

      Parameters

      • handler: ListToolsHandler

        Handler function that returns tool definitions

      Returns void

    • Set persisted widget state On ChatGPT: Persists session-scoped state On MCP Apps: Silent no-op (graceful degradation)

      Type Parameters

      • S

      Parameters

      • state: S

        State to persist

      Returns void

    • Set up automatic size change notifications

      Creates a ResizeObserver that automatically sends size changed notifications to the host when the document body resizes.

      Returns () => void

      Cleanup function to stop observing

    • Update the host's model context with app state (ext-apps v0.4.0+)

      Unlike sendMessage which triggers follow-up actions, context updates inform the model about app state without triggering responses.

      Context Persistence:

      • Each call replaces the previous context (not accumulated)
      • The host defers sending context to the model until the next user message
      • Only the most recent update is sent to the model

      Platform Implementation Details:

      • MCP Apps: Uses native protocol feature for pure context updates
      • ChatGPT: Uses setState/setWidgetState internally
        • Context persists for the widget's session lifetime
        • Both setState() and updateModelContext() expose data to the AI model
        • Use setState() for persistence-focused use cases
        • Use updateModelContext() for context-focused use cases
        • Important: Be mindful of data size when sending large structured content, as it may impact message context limits

      Reserved Keys:

      • Keys starting with underscore (_) in structuredContent are reserved for internal use and will be filtered out
      • Use alphanumeric keys for your application data

      Parameters

      Returns Promise<void>

      // Text content
      await client.updateModelContext({
        content: [{ type: "text", text: "User selected 3 items totaling $150" }]
      });

      // Structured content
      await client.updateModelContext({
        structuredContent: { selectedItems: 3, total: 150, currency: "USD" }
      });

    • Upload a file (ChatGPT only)

      Parameters

      • file: File

        File to upload

      Returns Promise<{ fileId: string }>

      File ID for later retrieval

      Error on unsupported platforms

    Settings

    Member Visibility

    On This Page

    Properties
    Methods