App | MCP Apps

Class App

Main class for MCP Apps to communicate with their host.

The App class provides a framework-agnostic way to build interactive MCP Apps that run inside host applications. It extends the MCP SDK's Protocol class and handles the connection lifecycle, initialization handshake, and bidirectional communication with the host.

Architecture

Views (Apps) act as MCP clients connecting to the host via PostMessageTransport. The host proxies requests to the actual MCP server and forwards responses back to the App.

Lifecycle

Create: Instantiate App with info and capabilities
Connect: Call connect() to establish transport and perform handshake
Interactive: Send requests, receive notifications, call tools
Teardown: Host sends teardown request before unmounting

Inherited Methods

As a subclass of ProtocolWithEvents, App inherits:

setRequestHandler() - Register handlers for requests from host
setNotificationHandler() - Register handlers for notifications from host
addEventListener() - Append a listener for a notification event (multi-listener)
removeEventListener() - Remove a previously added listener

See

ProtocolWithEvents for the DOM-model event system

Notification Setters (DOM-model `on*` handlers)

For common notifications, the App class provides getter/setter properties that follow DOM-model replace semantics (like el.onclick):

ontoolinput - Complete tool arguments from host
ontoolinputpartial - Streaming partial tool arguments
ontoolresult - Tool execution results
ontoolcancelled - Tool execution was cancelled by user or host
onhostcontextchanged - Host context changes (theme, locale, etc.)

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Example: Basic usage with PostMessageTransport

const app = new App(
  { name: "WeatherApp", version: "1.0.0" },
  {}, // capabilities
);

// Register handlers before connecting to ensure no notifications are missed
app.ontoolinput = (params) => {
  console.log("Tool arguments:", params.arguments);
};

await app.connect();

Hierarchy (View Summary)

ProtocolWithEvents<AppRequest, AppNotification, AppResult, AppEventMap>
- App

Index

Accessors

oncalltool

get oncalltool(): | (
    (
        params: {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            arguments?: { [key: string]: unknown };
            name: string;
            task?: { ttl?: number };
        },
        extra: RequestHandlerExtra,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: (...)
                        | (...);
                        sizes?: (...) | (...);
                        src: string;
                        theme?: (...) | (...) | (...);
                    }[];
                    mimeType?: string;
                    name: string;
                    size?: number;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: ...]: ... };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    >
)
| undefined
Returns
    | (
        (
            params: {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                arguments?: { [key: string]: unknown };
                name: string;
                task?: { ttl?: number };
            },
            extra: RequestHandlerExtra,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: (...)
                            | (...);
                            sizes?: (...) | (...);
                            src: string;
                            theme?: (...) | (...) | (...);
                        }[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: ...]: ... };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: ...]: ... };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >
    )
    | undefined
- Defined in src/app.ts:1048
set oncalltool(
    callback:
        | (
            (
                params: {
                    _meta?: {
                        "io.modelcontextprotocol/related-task"?: { taskId: string };
                        progressToken?: string | number;
                        [key: string]: unknown;
                    };
                    arguments?: { [key: string]: unknown };
                    name: string;
                    task?: { ttl?: number };
                },
                extra: RequestHandlerExtra,
            ) => Promise<
                {
                    _meta?: {
                        "io.modelcontextprotocol/related-task"?: { taskId: string };
                        progressToken?: string | number;
                        [key: string]: unknown;
                    };
                    content: (
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...)[];
                                lastModified?: string;
                                priority?: number;
                            };
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...)[];
                                lastModified?: string;
                                priority?: number;
                            };
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...)[];
                                lastModified?: string;
                                priority?: number;
                            };
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...)[];
                                lastModified?: string;
                                priority?: number;
                            };
                            description?: string;
                            icons?: {
                                mimeType?: (...)
                                | (...);
                                sizes?: (...) | (...);
                                src: string;
                                theme?: (...) | (...) | (...);
                            }[];
                            mimeType?: string;
                            name: string;
                            size?: number;
                            title?: string;
                            type: "resource_link";
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...)[];
                                lastModified?: string;
                                priority?: number;
                            };
                            resource: | {
                                _meta?: { [key: ...]: ... };
                                mimeType?: string;
                                text: string;
                                uri: string;
                            }
                            | {
                                _meta?: { [key: ...]: ... };
                                blob: string;
                                mimeType?: string;
                                uri: string;
                            };
                            type: "resource";
                        }
                    )[];
                    isError?: boolean;
                    structuredContent?: { [key: string]: unknown };
                    [key: string]: unknown;
                },
            >
        )
        | undefined,
): void
Parameters
- callback:
      | (
          (
              params: {
                  _meta?: {
                      "io.modelcontextprotocol/related-task"?: { taskId: string };
                      progressToken?: string | number;
                      [key: string]: unknown;
                  };
                  arguments?: { [key: string]: unknown };
                  name: string;
                  task?: { ttl?: number };
              },
              extra: RequestHandlerExtra,
          ) => Promise<
              {
                  _meta?: {
                      "io.modelcontextprotocol/related-task"?: { taskId: string };
                      progressToken?: string | number;
                      [key: string]: unknown;
                  };
                  content: (
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...)[];
                              lastModified?: string;
                              priority?: number;
                          };
                          text: string;
                          type: "text";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...)[];
                              lastModified?: string;
                              priority?: number;
                          };
                          data: string;
                          mimeType: string;
                          type: "image";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...)[];
                              lastModified?: string;
                              priority?: number;
                          };
                          data: string;
                          mimeType: string;
                          type: "audio";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...)[];
                              lastModified?: string;
                              priority?: number;
                          };
                          description?: string;
                          icons?: {
                              mimeType?: (...)
                              | (...);
                              sizes?: (...) | (...);
                              src: string;
                              theme?: (...) | (...) | (...);
                          }[];
                          mimeType?: string;
                          name: string;
                          size?: number;
                          title?: string;
                          type: "resource_link";
                          uri: string;
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...)[];
                              lastModified?: string;
                              priority?: number;
                          };
                          resource: | {
                              _meta?: { [key: ...]: ... };
                              mimeType?: string;
                              text: string;
                              uri: string;
                          }
                          | {
                              _meta?: { [key: ...]: ... };
                              blob: string;
                              mimeType?: string;
                              uri: string;
                          };
                          type: "resource";
                      }
                  )[];
                  isError?: boolean;
                  structuredContent?: { [key: string]: unknown };
                  [key: string]: unknown;
              },
          >
      )
      | undefined
Returns void
- Defined in src/app.ts:1051

onhostcontextchanged

get onhostcontextchanged(): ((params: McpUiHostContext) => void) | undefined
Convenience handler for host context changes (theme, locale, etc.).

Set this property to register a handler that will be called when the host's context changes, such as theme switching (light/dark), locale changes, or other environmental updates. Apps should respond by updating their UI accordingly.

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Notification params are automatically merged into the internal host context via onEventDispatch before any handler or listener fires. This means getHostContext will return the updated values even before your callback runs.

Register handlers before calling connect to avoid missing notifications.

Returns ((params: McpUiHostContext) => void) | undefined
Example: Respond to theme changes
```
app.onhostcontextchanged = (ctx) => {
  if (ctx.theme === "dark") {
    document.body.classList.add("dark-theme");
  } else {
    document.body.classList.remove("dark-theme");
  }
};
```
Deprecated
Use addEventListener("hostcontextchanged", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
See
- McpUiHostContextChangedNotification for the notification structure
- McpUiHostContext for the full context structure
- Defined in src/app.ts:948
set onhostcontextchanged(
callback: ((params: McpUiHostContext) => void) | undefined,
): void
Parameters
- callback: ((params: McpUiHostContext) => void) | undefined
Returns void
- Defined in src/app.ts:953

onlisttools

get onlisttools(): | (
    (
        params:
            | {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                cursor?: string;
            }
            | undefined,
        extra: RequestHandlerExtra,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            nextCursor?: string;
            tools: {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    destructiveHint?: boolean;
                    idempotentHint?: boolean;
                    openWorldHint?: boolean;
                    readOnlyHint?: boolean;
                    title?: string;
                };
                description?: string;
                execution?: { taskSupport?: "optional"
                | "required"
                | "forbidden" };
                icons?: {
                    mimeType?: string;
                    sizes?: (...)[];
                    src: string;
                    theme?: "light" | "dark";
                }[];
                inputSchema: {
                    properties?: { [key: string]: object };
                    required?: string[];
                    type: "object";
                    [key: string]: unknown;
                };
                name: string;
                outputSchema?: {
                    properties?: { [key: string]: object };
                    required?: string[];
                    type: "object";
                    [key: string]: unknown;
                };
                title?: string;
            }[];
            [key: string]: unknown;
        },
    >
)
| undefined
Returns
    | (
        (
            params:
                | {
                    _meta?: {
                        "io.modelcontextprotocol/related-task"?: { taskId: string };
                        progressToken?: string | number;
                        [key: string]: unknown;
                    };
                    cursor?: string;
                }
                | undefined,
            extra: RequestHandlerExtra,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                nextCursor?: string;
                tools: {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        destructiveHint?: boolean;
                        idempotentHint?: boolean;
                        openWorldHint?: boolean;
                        readOnlyHint?: boolean;
                        title?: string;
                    };
                    description?: string;
                    execution?: { taskSupport?: "optional"
                    | "required"
                    | "forbidden" };
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    inputSchema: {
                        properties?: { [key: string]: object };
                        required?: string[];
                        type: "object";
                        [key: string]: unknown;
                    };
                    name: string;
                    outputSchema?: {
                        properties?: { [key: string]: object };
                        required?: string[];
                        type: "object";
                        [key: string]: unknown;
                    };
                    title?: string;
                }[];
                [key: string]: unknown;
            },
        >
    )
    | undefined
- Defined in src/app.ts:1115
set onlisttools(
    callback:
        | (
            (
                params:
                    | {
                        _meta?: {
                            "io.modelcontextprotocol/related-task"?: { taskId: string };
                            progressToken?: string | number;
                            [key: string]: unknown;
                        };
                        cursor?: string;
                    }
                    | undefined,
                extra: RequestHandlerExtra,
            ) => Promise<
                {
                    _meta?: {
                        "io.modelcontextprotocol/related-task"?: { taskId: string };
                        progressToken?: string | number;
                        [key: string]: unknown;
                    };
                    nextCursor?: string;
                    tools: {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            destructiveHint?: boolean;
                            idempotentHint?: boolean;
                            openWorldHint?: boolean;
                            readOnlyHint?: boolean;
                            title?: string;
                        };
                        description?: string;
                        execution?: { taskSupport?: "optional"
                        | "required"
                        | "forbidden" };
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        inputSchema: {
                            properties?: { [key: string]: object };
                            required?: string[];
                            type: "object";
                            [key: string]: unknown;
                        };
                        name: string;
                        outputSchema?: {
                            properties?: { [key: string]: object };
                            required?: string[];
                            type: "object";
                            [key: string]: unknown;
                        };
                        title?: string;
                    }[];
                    [key: string]: unknown;
                },
            >
        )
        | undefined,
): void
Parameters
- callback:
      | (
          (
              params:
                  | {
                      _meta?: {
                          "io.modelcontextprotocol/related-task"?: { taskId: string };
                          progressToken?: string | number;
                          [key: string]: unknown;
                      };
                      cursor?: string;
                  }
                  | undefined,
              extra: RequestHandlerExtra,
          ) => Promise<
              {
                  _meta?: {
                      "io.modelcontextprotocol/related-task"?: { taskId: string };
                      progressToken?: string | number;
                      [key: string]: unknown;
                  };
                  nextCursor?: string;
                  tools: {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          destructiveHint?: boolean;
                          idempotentHint?: boolean;
                          openWorldHint?: boolean;
                          readOnlyHint?: boolean;
                          title?: string;
                      };
                      description?: string;
                      execution?: { taskSupport?: "optional"
                      | "required"
                      | "forbidden" };
                      icons?: {
                          mimeType?: string;
                          sizes?: (...)[];
                          src: string;
                          theme?: "light" | "dark";
                      }[];
                      inputSchema: {
                          properties?: { [key: string]: object };
                          required?: string[];
                          type: "object";
                          [key: string]: unknown;
                      };
                      name: string;
                      outputSchema?: {
                          properties?: { [key: string]: object };
                          required?: string[];
                          type: "object";
                          [key: string]: unknown;
                      };
                      title?: string;
                  }[];
                  [key: string]: unknown;
              },
          >
      )
      | undefined
Returns void
- Defined in src/app.ts:1118

onteardown

get onteardown(): | (
    (
        params: {},
        extra: RequestHandlerExtra,
    ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>
)
| undefined
Returns
    | (
        (
            params: {},
            extra: RequestHandlerExtra,
        ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>
    )
    | undefined
- Defined in src/app.ts:994
set onteardown(
    callback:
        | (
            (
                params: {},
                extra: RequestHandlerExtra,
            ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>
        )
        | undefined,
): void
Parameters
- callback:
      | (
          (
              params: {},
              extra: RequestHandlerExtra,
          ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>
      )
      | undefined
Returns void
- Defined in src/app.ts:997

ontoolcancelled

get ontoolcancelled(): ((params: { reason?: string }) => void) | undefined
Convenience handler for receiving tool cancellation notifications from the host.

Set this property to register a handler that will be called when the host notifies that tool execution was cancelled. This can occur for various reasons including user action, sampling error, classifier intervention, or other interruptions. Apps should update their state and display appropriate feedback.

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Register handlers before calling connect to avoid missing notifications.

Returns ((params: { reason?: string }) => void) | undefined
Example: Handle tool cancellation
```
app.ontoolcancelled = (params) => {
  console.log("Tool cancelled:", params.reason);
  // Update your UI to show cancellation state
};
```
Deprecated
Use addEventListener("toolcancelled", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
See
- McpUiToolCancelledNotification for the notification structure
- ontoolresult for successful tool completion
- Defined in src/app.ts:901
set ontoolcancelled(
callback: ((params: { reason?: string }) => void) | undefined,
): void
Parameters
- callback: ((params: { reason?: string }) => void) | undefined
Returns void
- Defined in src/app.ts:906

ontoolinput

get ontoolinput(): | ((params: { arguments?: Record<string, unknown> }) => void)
| undefined
Convenience handler for receiving complete tool input from the host.

Set this property to register a handler that will be called when the host sends a tool's complete arguments. This is sent after a tool call begins and before the tool result is available.

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Register handlers before calling connect to avoid missing notifications.

Returns ((params: { arguments?: Record<string, unknown> }) => void) | undefined
Example
```
// Register before connecting to ensure no notifications are missed
app.ontoolinput = (params) => {
  console.log("Tool:", params.arguments);
  // Update your UI with the tool arguments
};
await app.connect();
```
Deprecated
Use addEventListener("toolinput", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.

See
McpUiToolInputNotification for the notification structure
- Defined in src/app.ts:768
set ontoolinput(
    callback:
        | ((params: { arguments?: Record<string, unknown> }) => void)
        | undefined,
): void
Parameters
- callback: ((params: { arguments?: Record<string, unknown> }) => void) | undefined
Returns void
- Defined in src/app.ts:773

ontoolinputpartial

get ontoolinputpartial(): | (
(params: { arguments?: Record<string, unknown> }) => void
)
| undefined
Convenience handler for receiving streaming partial tool input from the host.

Set this property to register a handler that will be called as the host streams partial tool arguments during tool call initialization. This enables progressive rendering of tool arguments before they're complete.

Important: Partial arguments are "healed" JSON — the host closes unclosed brackets/braces to produce valid JSON. This means objects may be incomplete (e.g., the last item in an array may be truncated). Use partial data only for preview UI, not for critical operations.

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Register handlers before calling connect to avoid missing notifications.

Returns ((params: { arguments?: Record<string, unknown> }) => void) | undefined
Example: Progressive rendering of tool arguments
```
const codePreview = document.querySelector<HTMLPreElement>("#code-preview")!;
const canvas = document.querySelector<HTMLCanvasElement>("#canvas")!;

app.ontoolinputpartial = (params) => {
  codePreview.textContent = (params.arguments?.code as string) ?? "";
  codePreview.style.display = "block";
  canvas.style.display = "none";
};

app.ontoolinput = (params) => {
  codePreview.style.display = "none";
  canvas.style.display = "block";
  render(params.arguments?.code as string);
};
```
Deprecated
Use addEventListener("toolinputpartial", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
See
- McpUiToolInputPartialNotification for the notification structure
- ontoolinput for the complete tool input handler
- Defined in src/app.ts:821
set ontoolinputpartial(
    callback:
        | ((params: { arguments?: Record<string, unknown> }) => void)
        | undefined,
): void
Parameters
- callback: ((params: { arguments?: Record<string, unknown> }) => void) | undefined
Returns void
- Defined in src/app.ts:826

ontoolresult

get ontoolresult(): | (
    (
        params: {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    mimeType?: string;
                    name: string;
                    size?: number;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: string]: unknown };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    ) => void
)
| undefined
Convenience handler for receiving tool execution results from the host.

Set this property to register a handler that will be called when the host sends the result of a tool execution. This is sent after the tool completes on the MCP server, allowing your app to display the results or update its state.

Assigning replaces the previous handler; assigning undefined clears it. Use addEventListener to attach multiple listeners without replacing.

Register handlers before calling connect to avoid missing notifications.

Returns
    | (
        (
            params: {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        ) => void
    )
    | undefined
Example: Display tool execution results
```
app.ontoolresult = (params) => {
  if (params.isError) {
    console.error("Tool execution failed:", params.content);
  } else if (params.content) {
    console.log("Tool output:", params.content);
  }
};
```
Deprecated
Use addEventListener("toolresult", handler) instead — it composes with other listeners and supports cleanup via removeEventListener.
See
- McpUiToolResultNotification for the notification structure
- ontoolinput for the initial tool input handler
- Defined in src/app.ts:862
set ontoolresult(
    callback:
        | (
            (
                params: {
                    _meta?: {
                        "io.modelcontextprotocol/related-task"?: { taskId: string };
                        progressToken?: string | number;
                        [key: string]: unknown;
                    };
                    content: (
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: ((...) | (...))[];
                                lastModified?: string;
                                priority?: number;
                            };
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: ((...) | (...))[];
                                lastModified?: string;
                                priority?: number;
                            };
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: ((...) | (...))[];
                                lastModified?: string;
                                priority?: number;
                            };
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: ((...) | (...))[];
                                lastModified?: string;
                                priority?: number;
                            };
                            description?: string;
                            icons?: {
                                mimeType?: string;
                                sizes?: (...)[];
                                src: string;
                                theme?: "light" | "dark";
                            }[];
                            mimeType?: string;
                            name: string;
                            size?: number;
                            title?: string;
                            type: "resource_link";
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: ((...) | (...))[];
                                lastModified?: string;
                                priority?: number;
                            };
                            resource: | {
                                _meta?: { [key: string]: unknown };
                                mimeType?: string;
                                text: string;
                                uri: string;
                            }
                            | {
                                _meta?: { [key: string]: unknown };
                                blob: string;
                                mimeType?: string;
                                uri: string;
                            };
                            type: "resource";
                        }
                    )[];
                    isError?: boolean;
                    structuredContent?: { [key: string]: unknown };
                    [key: string]: unknown;
                },
            ) => void
        )
        | undefined,
): void
Parameters
- callback:
      | (
          (
              params: {
                  _meta?: {
                      "io.modelcontextprotocol/related-task"?: { taskId: string };
                      progressToken?: string | number;
                      [key: string]: unknown;
                  };
                  content: (
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: ((...) | (...))[];
                              lastModified?: string;
                              priority?: number;
                          };
                          text: string;
                          type: "text";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: ((...) | (...))[];
                              lastModified?: string;
                              priority?: number;
                          };
                          data: string;
                          mimeType: string;
                          type: "image";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: ((...) | (...))[];
                              lastModified?: string;
                              priority?: number;
                          };
                          data: string;
                          mimeType: string;
                          type: "audio";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: ((...) | (...))[];
                              lastModified?: string;
                              priority?: number;
                          };
                          description?: string;
                          icons?: {
                              mimeType?: string;
                              sizes?: (...)[];
                              src: string;
                              theme?: "light" | "dark";
                          }[];
                          mimeType?: string;
                          name: string;
                          size?: number;
                          title?: string;
                          type: "resource_link";
                          uri: string;
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: ((...) | (...))[];
                              lastModified?: string;
                              priority?: number;
                          };
                          resource: | {
                              _meta?: { [key: string]: unknown };
                              mimeType?: string;
                              text: string;
                              uri: string;
                          }
                          | {
                              _meta?: { [key: string]: unknown };
                              blob: string;
                              mimeType?: string;
                              uri: string;
                          };
                          type: "resource";
                      }
                  )[];
                  isError?: boolean;
                  structuredContent?: { [key: string]: unknown };
                  [key: string]: unknown;
              },
          ) => void
      )
      | undefined
Returns void
- Defined in src/app.ts:867

transport

get transport(): Transport | undefined
Returns Transport | undefined
Inherited from AppBridge.transport
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:283

Constructors

constructor

new App(
    _appInfo: {
        description?: string;
        icons?: {
            mimeType?: string;
            sizes?: string[];
            src: string;
            theme?: "light" | "dark";
        }[];
        name: string;
        title?: string;
        version: string;
        websiteUrl?: string;
    },
    _capabilities?: McpUiAppCapabilities,
    options?: AppOptions,
): App
Create a new MCP App instance.
Parameters
- _appInfo: {
      description?: string;
      icons?: {
          mimeType?: string;
          sizes?: string[];
          src: string;
          theme?: "light" | "dark";
      }[];
      name: string;
      title?: string;
      version: string;
      websiteUrl?: string;
  }
  App identification (name and version)
- _capabilities: McpUiAppCapabilities = {}
  Features and capabilities this app provides
- options: AppOptions = ...
  Configuration options including autoResize behavior
Returns App
Example
```
const app = new App(
  { name: "MyApp", version: "1.0.0" },
  { tools: { listChanged: true } }, // capabilities
  { autoResize: true }, // options
);
```
Overrides ProtocolWithEvents.constructor
- Defined in src/app.ts:471

Methods

addEventListener

addEventListener<K extends keyof AppEventMap>(
event: K,
handler: (params: AppEventMap[K]) => void,
): void
Add a listener for a notification event.

Unlike the singular on* handler, calling this multiple times appends listeners rather than replacing them. All registered listeners fire in insertion order after the on* handler when the notification arrives.

Registration is lazy: the first call (for a given event, from either this method or the on* setter) registers a dispatcher with the base Protocol.
Type Parameters
- K extends keyof AppEventMap
Parameters
- event: K
  Event name (a key of the EventMap type parameter).
- handler: (params: AppEventMap[K]) => void
  Listener invoked with the notification params.
Returns void
Overrides ProtocolWithEvents.addEventListener
- Defined in src/app.ts:438

assertCanSetRequestHandler

assertCanSetRequestHandler(method: string): void
Asserts that a request handler has not already been set for the given method, in preparation for a new one being automatically installed.
Parameters
- method: string
Returns void
Inherited from ProtocolWithEvents.assertCanSetRequestHandler
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:397

assertCapabilityForMethod

assertCapabilityForMethod(
    method:
        | "ui/open-link"
        | "ui/download-file"
        | "ui/message"
        | "ui/update-model-context"
        | "ui/resource-teardown"
        | "ui/initialize"
        | "ui/request-display-mode"
        | "tools/call"
        | "tools/list"
        | "resources/list"
        | "resources/templates/list"
        | "resources/read"
        | "prompts/list"
        | "sampling/createMessage"
        | "ping",
): void
Internal
Verify that the host supports the capability required for the given request method.
Parameters
- method:
      | "ui/open-link"
      | "ui/download-file"
      | "ui/message"
      | "ui/update-model-context"
      | "ui/resource-teardown"
      | "ui/initialize"
      | "ui/request-display-mode"
      | "tools/call"
      | "tools/list"
      | "resources/list"
      | "resources/templates/list"
      | "resources/read"
      | "prompts/list"
      | "sampling/createMessage"
      | "ping"
Returns void
Overrides ProtocolWithEvents.assertCapabilityForMethod
- Defined in src/app.ts:1142

assertNotificationCapability

assertNotificationCapability(
    _method:
        | "ui/notifications/sandbox-proxy-ready"
        | "ui/notifications/sandbox-resource-ready"
        | "ui/notifications/size-changed"
        | "ui/notifications/tool-input"
        | "ui/notifications/tool-input-partial"
        | "ui/notifications/tool-result"
        | "ui/notifications/tool-cancelled"
        | "ui/notifications/host-context-changed"
        | "ui/notifications/request-teardown"
        | "ui/notifications/initialized"
        | "notifications/tools/list_changed"
        | "notifications/resources/list_changed"
        | "notifications/prompts/list_changed"
        | "notifications/message",
): void
Internal
Verify that the app supports the capability required for the given notification method.
Parameters
- _method:
      | "ui/notifications/sandbox-proxy-ready"
      | "ui/notifications/sandbox-resource-ready"
      | "ui/notifications/size-changed"
      | "ui/notifications/tool-input"
      | "ui/notifications/tool-input-partial"
      | "ui/notifications/tool-result"
      | "ui/notifications/tool-cancelled"
      | "ui/notifications/host-context-changed"
      | "ui/notifications/request-teardown"
      | "ui/notifications/initialized"
      | "notifications/tools/list_changed"
      | "notifications/resources/list_changed"
      | "notifications/prompts/list_changed"
      | "notifications/message"
Returns void
Overrides ProtocolWithEvents.assertNotificationCapability
- Defined in src/app.ts:1180

assertRequestHandlerCapability

assertRequestHandlerCapability(
    method:
        | "ui/open-link"
        | "ui/download-file"
        | "ui/message"
        | "ui/update-model-context"
        | "ui/resource-teardown"
        | "ui/initialize"
        | "ui/request-display-mode"
        | "tools/call"
        | "tools/list"
        | "resources/list"
        | "resources/templates/list"
        | "resources/read"
        | "prompts/list"
        | "sampling/createMessage"
        | "ping",
): void
Internal
Verify that the app declared the capability required for the given request method.
Parameters
- method:
      | "ui/open-link"
      | "ui/download-file"
      | "ui/message"
      | "ui/update-model-context"
      | "ui/resource-teardown"
      | "ui/initialize"
      | "ui/request-display-mode"
      | "tools/call"
      | "tools/list"
      | "resources/list"
      | "resources/templates/list"
      | "resources/read"
      | "prompts/list"
      | "sampling/createMessage"
      | "ping"
Returns void
Overrides ProtocolWithEvents.assertRequestHandlerCapability
- Defined in src/app.ts:1158

`Protected`assertTaskCapability

assertTaskCapability(_method: string): void
Internal
Verify that task creation is supported for the given request method.
Parameters
- _method: string
Returns void
Overrides ProtocolWithEvents.assertTaskCapability
- Defined in src/app.ts:1188

`Protected`assertTaskHandlerCapability

assertTaskHandlerCapability(_method: string): void
Internal
Verify that task handler is supported for the given method.
Parameters
- _method: string
Returns void
Overrides ProtocolWithEvents.assertTaskHandlerCapability
- Defined in src/app.ts:1196

callServerTool

callServerTool(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        arguments?: { [key: string]: unknown };
        name: string;
        task?: { ttl?: number };
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                description?: string;
                icons?: {
                    mimeType?: string;
                    sizes?: string[];
                    src: string;
                    theme?: "light"
                    | "dark";
                }[];
                mimeType?: string;
                name: string;
                size?: number;
                title?: string;
                type: "resource_link";
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                resource: | {
                    _meta?: { [key: string]: unknown };
                    mimeType?: string;
                    text: string;
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    blob: string;
                    mimeType?: string;
                    uri: string;
                };
                type: "resource";
            }
        )[];
        isError?: boolean;
        structuredContent?: { [key: string]: unknown };
        [key: string]: unknown;
    },
>
Call a tool on the originating MCP server (proxied through the host).

Apps can call tools to fetch fresh data or trigger server-side actions. The host proxies the request to the actual MCP server and returns the result.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      arguments?: { [key: string]: unknown };
      name: string;
      task?: { ttl?: number };
  }
  Tool name and arguments
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                description?: string;
                icons?: {
                    mimeType?: string;
                    sizes?: string[];
                    src: string;
                    theme?: "light"
                    | "dark";
                }[];
                mimeType?: string;
                name: string;
                size?: number;
                title?: string;
                type: "resource_link";
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                resource: | {
                    _meta?: { [key: string]: unknown };
                    mimeType?: string;
                    text: string;
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    blob: string;
                    mimeType?: string;
                    uri: string;
                };
                type: "resource";
            }
        )[];
        isError?: boolean;
        structuredContent?: { [key: string]: unknown };
        [key: string]: unknown;
    },
>
Tool execution result
Throws
If the tool does not exist on the server

Throws
If the request times out or the connection is lost

Throws
If the host rejects the request

Note: Tool-level execution errors are returned in the result with isError: true rather than throwing exceptions. Always check result.isError to distinguish between transport failures (thrown) and tool execution failures (returned).
Example: Fetch updated weather data
```
try {
  const result = await app.callServerTool({
    name: "get_weather",
    arguments: { location: "Tokyo" },
  });
  if (result.isError) {
    console.error("Tool returned error:", result.content);
  } else {
    console.log(result.content);
  }
} catch (error) {
  console.error("Tool call failed:", error);
}
```
- Defined in src/app.ts:1235

`Protected`cancelTask

cancelTask(
    params: { taskId: string },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        createdAt: string;
        lastUpdatedAt: string;
        pollInterval?: number;
        status: | "working"
        | "input_required"
        | "completed"
        | "failed"
        | "cancelled";
        statusMessage?: string;
        taskId: string;
        ttl: number
        | null;
    },
>
Experimental
Cancels a specific task.

Use client.experimental.tasks.cancelTask() to access this method.
Parameters
- params: { taskId: string }
- Optionaloptions: RequestOptions
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        createdAt: string;
        lastUpdatedAt: string;
        pollInterval?: number;
        status: | "working"
        | "input_required"
        | "completed"
        | "failed"
        | "cancelled";
        statusMessage?: string;
        taskId: string;
        ttl: number
        | null;
    },
>
Inherited from ProtocolWithEvents.cancelTask
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:377

close

close(): Promise<void>
Closes the connection.

Returns Promise<void>
Inherited from ProtocolWithEvents.close
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:287

connect

connect(transport?: Transport, options?: RequestOptions): Promise<void>
Establish connection with the host and perform initialization handshake.

This method performs the following steps:
1. Connects the transport layer
2. Sends ui/initialize request with app info and capabilities
3. Receives host capabilities and context in response
4. Sends ui/notifications/initialized notification
5. Sets up auto-resize using setupSizeChangedNotifications if enabled (default)
If initialization fails, the connection is automatically closed and an error is thrown.
Parameters
- transport: Transport = ...
  Transport layer (typically PostMessageTransport)
- Optionaloptions: RequestOptions
  Request options for the initialize request
Returns Promise<void>
Throws
If initialization fails or connection is lost
Example: Connect with PostMessageTransport
```
const app = new App({ name: "MyApp", version: "1.0.0" }, {});

try {
  await app.connect(new PostMessageTransport(window.parent, window.parent));
  console.log("Connected successfully!");
} catch (error) {
  console.error("Failed to connect:", error);
}
```
See
- McpUiInitializeRequest for the initialization request structure
- McpUiInitializedNotification for the initialized notification
- PostMessageTransport for the typical transport implementation
Overrides ProtocolWithEvents.connect
- Defined in src/app.ts:1943

createSamplingMessage

createSamplingMessage(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        includeContext?: "none"
        | "thisServer"
        | "allServers";
        maxTokens: number;
        messages: {
            _meta?: { [key: string]: unknown };
            content:
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    id: string;
                    input: { [key: string]: unknown };
                    name: string;
                    type: "tool_use";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    content: (
                        | {
                            _meta?: { [key: ...]: ... };
                            annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: { [key: ...]: ... };
                            annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: { [key: ...]: ... };
                            annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: { [key: ...]: ... };
                            annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                            description?: string;
                            icons?: (...)[];
                            mimeType?: string;
                            name: string;
                            size?: number;
                            title?: string;
                            type: "resource_link";
                            uri: string;
                        }
                        | {
                            _meta?: { [key: ...]: ... };
                            annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                            resource:
                                | { _meta?: ...; mimeType?: ...; text: ...; uri: ... }
                                | { _meta?: ...; blob: ...; mimeType?: ...; uri: ... };
                            type: "resource";
                        }
                    )[];
                    isError?: boolean;
                    structuredContent?: { [key: string]: unknown };
                    toolUseId: string;
                    type: "tool_result";
                }
                | (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        id: string;
                        input: { [key: string]: unknown };
                        name: string;
                        type: "tool_use";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        content: (
                            | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                description?: ...;
                                icons?: ...;
                                mimeType?: ...;
                                name: ...;
                                size?: ...;
                                title?: ...;
                                type: ...;
                                uri: ...;
                            }
                            | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                        )[];
                        isError?: boolean;
                        structuredContent?: { [key: string]: unknown };
                        toolUseId: string;
                        type: "tool_result";
                    }
                )[];
            role: "user"
            | "assistant";
        }[];
        metadata?: object;
        modelPreferences?: {
            costPriority?: number;
            hints?: { name?: string }[];
            intelligencePriority?: number;
            speedPriority?: number;
        };
        stopSequences?: string[];
        systemPrompt?: string;
        task?: { ttl?: number };
        temperature?: number;
        toolChoice?: { mode?: "required" | "none" | "auto" };
        tools?: {
            _meta?: { [key: string]: unknown };
            annotations?: {
                destructiveHint?: boolean;
                idempotentHint?: boolean;
                openWorldHint?: boolean;
                readOnlyHint?: boolean;
                title?: string;
            };
            description?: string;
            execution?: { taskSupport?: "optional"
            | "required"
            | "forbidden" };
            icons?: {
                mimeType?: string;
                sizes?: string[];
                src: string;
                theme?: "light" | "dark";
            }[];
            inputSchema: {
                properties?: { [key: string]: object };
                required?: string[];
                type: "object";
                [key: string]: unknown;
            };
            name: string;
            outputSchema?: {
                properties?: { [key: string]: object };
                required?: string[];
                type: "object";
                [key: string]: unknown;
            };
            title?: string;
        }[];
    } & { tools?: undefined },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            text: string;
            type: "text";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "image";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "audio";
        };
        model: string;
        role: "user"
        | "assistant";
        stopReason?: string;
        [key: string]: unknown;
    },
>
Request an LLM completion from the host (standard MCP sampling/createMessage).

Enables the app to use the host's model connection for completions. The host has full discretion over which model to select and MAY modify or reject the request (human-in-the-loop). Check getHostCapabilities()?.sampling before calling — hosts without this capability will reject the request.

This method reuses the stock MCP CreateMessageRequest shape. When params.tools is provided, the result is parsed with the extended schema that permits stopReason: "toolUse" and array content containing tool_use blocks.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      includeContext?: "none"
      | "thisServer"
      | "allServers";
      maxTokens: number;
      messages: {
          _meta?: { [key: string]: unknown };
          content:
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  text: string;
                  type: "text";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "image";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "audio";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  id: string;
                  input: { [key: string]: unknown };
                  name: string;
                  type: "tool_use";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  content: (
                      | {
                          _meta?: { [key: ...]: ... };
                          annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                          text: string;
                          type: "text";
                      }
                      | {
                          _meta?: { [key: ...]: ... };
                          annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                          data: string;
                          mimeType: string;
                          type: "image";
                      }
                      | {
                          _meta?: { [key: ...]: ... };
                          annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                          data: string;
                          mimeType: string;
                          type: "audio";
                      }
                      | {
                          _meta?: { [key: ...]: ... };
                          annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                          description?: string;
                          icons?: (...)[];
                          mimeType?: string;
                          name: string;
                          size?: number;
                          title?: string;
                          type: "resource_link";
                          uri: string;
                      }
                      | {
                          _meta?: { [key: ...]: ... };
                          annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                          resource:
                              | { _meta?: ...; mimeType?: ...; text: ...; uri: ... }
                              | { _meta?: ...; blob: ...; mimeType?: ...; uri: ... };
                          type: "resource";
                      }
                  )[];
                  isError?: boolean;
                  structuredContent?: { [key: string]: unknown };
                  toolUseId: string;
                  type: "tool_result";
              }
              | (
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...) | (...);
                          lastModified?: (...) | (...);
                          priority?: (...) | (...);
                      };
                      text: string;
                      type: "text";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...) | (...);
                          lastModified?: (...) | (...);
                          priority?: (...) | (...);
                      };
                      data: string;
                      mimeType: string;
                      type: "image";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...) | (...);
                          lastModified?: (...) | (...);
                          priority?: (...) | (...);
                      };
                      data: string;
                      mimeType: string;
                      type: "audio";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      id: string;
                      input: { [key: string]: unknown };
                      name: string;
                      type: "tool_use";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      content: (
                          | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                          | {
                              _meta?: ...;
                              annotations?: ...;
                              data: ...;
                              mimeType: ...;
                              type: ...;
                          }
                          | {
                              _meta?: ...;
                              annotations?: ...;
                              data: ...;
                              mimeType: ...;
                              type: ...;
                          }
                          | {
                              _meta?: ...;
                              annotations?: ...;
                              description?: ...;
                              icons?: ...;
                              mimeType?: ...;
                              name: ...;
                              size?: ...;
                              title?: ...;
                              type: ...;
                              uri: ...;
                          }
                          | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                      )[];
                      isError?: boolean;
                      structuredContent?: { [key: string]: unknown };
                      toolUseId: string;
                      type: "tool_result";
                  }
              )[];
          role: "user"
          | "assistant";
      }[];
      metadata?: object;
      modelPreferences?: {
          costPriority?: number;
          hints?: { name?: string }[];
          intelligencePriority?: number;
          speedPriority?: number;
      };
      stopSequences?: string[];
      systemPrompt?: string;
      task?: { ttl?: number };
      temperature?: number;
      toolChoice?: { mode?: "required" | "none" | "auto" };
      tools?: {
          _meta?: { [key: string]: unknown };
          annotations?: {
              destructiveHint?: boolean;
              idempotentHint?: boolean;
              openWorldHint?: boolean;
              readOnlyHint?: boolean;
              title?: string;
          };
          description?: string;
          execution?: { taskSupport?: "optional"
          | "required"
          | "forbidden" };
          icons?: {
              mimeType?: string;
              sizes?: string[];
              src: string;
              theme?: "light" | "dark";
          }[];
          inputSchema: {
              properties?: { [key: string]: object };
              required?: string[];
              type: "object";
              [key: string]: unknown;
          };
          name: string;
          outputSchema?: {
              properties?: { [key: string]: object };
              required?: string[];
              type: "object";
              [key: string]: unknown;
          };
          title?: string;
      }[];
  } & { tools?: undefined }
  Standard MCP CreateMessageRequest params (messages, maxTokens, systemPrompt, temperature, modelPreferences, tools, toolChoice, etc.)
- Optionaloptions: RequestOptions
  Request options (timeout, abort signal)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            text: string;
            type: "text";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "image";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "audio";
        };
        model: string;
        role: "user"
        | "assistant";
        stopReason?: string;
        [key: string]: unknown;
    },
>
CreateMessageResult (single content block) or CreateMessageResultWithTools (array content, may include tool_use blocks) depending on whether tools was set
Throws
If the host rejects the request or does not support sampling

Throws
If the request times out or the connection is lost
Example: Simple completion
```
const result = await app.createSamplingMessage({
  messages: [
    {
      role: "user",
      content: { type: "text", text: "Summarize this in one line." },
    },
  ],
  maxTokens: 100,
});
console.log(result.content);
```
Example: Agentic loop with tools
```
if (!app.getHostCapabilities()?.sampling?.tools) return;

const result = await app.createSamplingMessage({
  messages,
  maxTokens: 1024,
  tools: [
    {
      name: "get_weather",
      description: "Get the current weather",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
      },
    },
  ],
});
if (result.stopReason === "toolUse") {
  // result.content may be an array containing tool_use blocks
}
```
See
- CreateMessageRequest from @modelcontextprotocol/sdk for the request type
- CreateMessageResult / CreateMessageResultWithTools from @modelcontextprotocol/sdk for result types
- Defined in src/app.ts:1421
createSamplingMessage(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        includeContext?: "none"
        | "thisServer"
        | "allServers";
        maxTokens: number;
        messages: {
            _meta?: { [key: string]: unknown };
            content:
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    id: string;
                    input: { [key: string]: unknown };
                    name: string;
                    type: "tool_use";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    content: (
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            description?: string;
                            icons?: { mimeType?: ...; sizes?: ...; src: ...; theme?: ... }[];
                            mimeType?: string;
                            name: string;
                            size?: number;
                            title?: string;
                            type: "resource_link";
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            resource: | {
                                _meta?: (...)
                                | (...);
                                mimeType?: (...) | (...);
                                text: string;
                                uri: string;
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                blob: string;
                                mimeType?: (...) | (...);
                                uri: string;
                            };
                            type: "resource";
                        }
                    )[];
                    isError?: boolean;
                    structuredContent?: { [key: string]: unknown };
                    toolUseId: string;
                    type: "tool_result";
                }
                | (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...)[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        id: string;
                        input: { [key: string]: unknown };
                        name: string;
                        type: "tool_use";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        content: (
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                text: string;
                                type: "text";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                data: string;
                                mimeType: string;
                                type: "image";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                data: string;
                                mimeType: string;
                                type: "audio";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                description?: (...) | (...);
                                icons?: (...) | (...);
                                mimeType?: (...) | (...);
                                name: string;
                                size?: (...) | (...);
                                title?: (...) | (...);
                                type: "resource_link";
                                uri: string;
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                resource: (...) | (...);
                                type: "resource";
                            }
                        )[];
                        isError?: boolean;
                        structuredContent?: { [key: string]: unknown };
                        toolUseId: string;
                        type: "tool_result";
                    }
                )[];
            role: "user"
            | "assistant";
        }[];
        metadata?: object;
        modelPreferences?: {
            costPriority?: number;
            hints?: { name?: string }[];
            intelligencePriority?: number;
            speedPriority?: number;
        };
        stopSequences?: string[];
        systemPrompt?: string;
        task?: { ttl?: number };
        temperature?: number;
        toolChoice?: { mode?: "required" | "none" | "auto" };
        tools?: {
            _meta?: { [key: string]: unknown };
            annotations?: {
                destructiveHint?: boolean;
                idempotentHint?: boolean;
                openWorldHint?: boolean;
                readOnlyHint?: boolean;
                title?: string;
            };
            description?: string;
            execution?: { taskSupport?: "optional"
            | "required"
            | "forbidden" };
            icons?: {
                mimeType?: string;
                sizes?: string[];
                src: string;
                theme?: "light" | "dark";
            }[];
            inputSchema: {
                properties?: { [key: string]: object };
                required?: string[];
                type: "object";
                [key: string]: unknown;
            };
            name: string;
            outputSchema?: {
                properties?: { [key: string]: object };
                required?: string[];
                type: "object";
                [key: string]: unknown;
            };
            title?: string;
        }[];
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            text: string;
            type: "text";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "image";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "audio";
        }
        | {
            _meta?: { [key: string]: unknown };
            id: string;
            input: { [key: string]: unknown };
            name: string;
            type: "tool_use";
        }
        | {
            _meta?: { [key: string]: unknown };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: (...)
                        | (...);
                        sizes?: (...) | (...);
                        src: string;
                        theme?: (...) | (...) | (...);
                    }[];
                    mimeType?: string;
                    name: string;
                    size?: number;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: ...]: ... };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            toolUseId: string;
            type: "tool_result";
        }
        | (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            }
            | {
                _meta?: { [key: string]: unknown };
                id: string;
                input: { [key: string]: unknown };
                name: string;
                type: "tool_use";
            }
            | {
                _meta?: { [key: string]: unknown };
                content: (
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        description?: string;
                        icons?: (...)[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        resource:
                            | { _meta?: ...; mimeType?: ...; text: ...; uri: ... }
                            | { _meta?: ...; blob: ...; mimeType?: ...; uri: ... };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                toolUseId: string;
                type: "tool_result";
            }
        )[];
        model: string;
        role: "user"
        | "assistant";
        stopReason?: string;
        [key: string]: unknown;
    },
>
Request an LLM completion from the host (standard MCP sampling/createMessage).

Enables the app to use the host's model connection for completions. The host has full discretion over which model to select and MAY modify or reject the request (human-in-the-loop). Check getHostCapabilities()?.sampling before calling — hosts without this capability will reject the request.

This method reuses the stock MCP CreateMessageRequest shape. When params.tools is provided, the result is parsed with the extended schema that permits stopReason: "toolUse" and array content containing tool_use blocks.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      includeContext?: "none"
      | "thisServer"
      | "allServers";
      maxTokens: number;
      messages: {
          _meta?: { [key: string]: unknown };
          content:
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      lastModified?: string;
                      priority?: number;
                  };
                  text: string;
                  type: "text";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "image";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ("user" | "assistant")[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "audio";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  id: string;
                  input: { [key: string]: unknown };
                  name: string;
                  type: "tool_use";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  content: (
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          text: string;
                          type: "text";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          data: string;
                          mimeType: string;
                          type: "image";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          data: string;
                          mimeType: string;
                          type: "audio";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          description?: string;
                          icons?: { mimeType?: ...; sizes?: ...; src: ...; theme?: ... }[];
                          mimeType?: string;
                          name: string;
                          size?: number;
                          title?: string;
                          type: "resource_link";
                          uri: string;
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          resource: | {
                              _meta?: (...)
                              | (...);
                              mimeType?: (...) | (...);
                              text: string;
                              uri: string;
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              blob: string;
                              mimeType?: (...) | (...);
                              uri: string;
                          };
                          type: "resource";
                      }
                  )[];
                  isError?: boolean;
                  structuredContent?: { [key: string]: unknown };
                  toolUseId: string;
                  type: "tool_result";
              }
              | (
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...)[];
                          lastModified?: string;
                          priority?: number;
                      };
                      text: string;
                      type: "text";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...)[];
                          lastModified?: string;
                          priority?: number;
                      };
                      data: string;
                      mimeType: string;
                      type: "image";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      annotations?: {
                          audience?: (...)[];
                          lastModified?: string;
                          priority?: number;
                      };
                      data: string;
                      mimeType: string;
                      type: "audio";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      id: string;
                      input: { [key: string]: unknown };
                      name: string;
                      type: "tool_use";
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      content: (
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              text: string;
                              type: "text";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              data: string;
                              mimeType: string;
                              type: "image";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              data: string;
                              mimeType: string;
                              type: "audio";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              description?: (...) | (...);
                              icons?: (...) | (...);
                              mimeType?: (...) | (...);
                              name: string;
                              size?: (...) | (...);
                              title?: (...) | (...);
                              type: "resource_link";
                              uri: string;
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              resource: (...) | (...);
                              type: "resource";
                          }
                      )[];
                      isError?: boolean;
                      structuredContent?: { [key: string]: unknown };
                      toolUseId: string;
                      type: "tool_result";
                  }
              )[];
          role: "user"
          | "assistant";
      }[];
      metadata?: object;
      modelPreferences?: {
          costPriority?: number;
          hints?: { name?: string }[];
          intelligencePriority?: number;
          speedPriority?: number;
      };
      stopSequences?: string[];
      systemPrompt?: string;
      task?: { ttl?: number };
      temperature?: number;
      toolChoice?: { mode?: "required" | "none" | "auto" };
      tools?: {
          _meta?: { [key: string]: unknown };
          annotations?: {
              destructiveHint?: boolean;
              idempotentHint?: boolean;
              openWorldHint?: boolean;
              readOnlyHint?: boolean;
              title?: string;
          };
          description?: string;
          execution?: { taskSupport?: "optional"
          | "required"
          | "forbidden" };
          icons?: {
              mimeType?: string;
              sizes?: string[];
              src: string;
              theme?: "light" | "dark";
          }[];
          inputSchema: {
              properties?: { [key: string]: object };
              required?: string[];
              type: "object";
              [key: string]: unknown;
          };
          name: string;
          outputSchema?: {
              properties?: { [key: string]: object };
              required?: string[];
              type: "object";
              [key: string]: unknown;
          };
          title?: string;
      }[];
  }
  Standard MCP CreateMessageRequest params (messages, maxTokens, systemPrompt, temperature, modelPreferences, tools, toolChoice, etc.)
- Optionaloptions: RequestOptions
  Request options (timeout, abort signal)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            text: string;
            type: "text";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "image";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "audio";
        }
        | {
            _meta?: { [key: string]: unknown };
            id: string;
            input: { [key: string]: unknown };
            name: string;
            type: "tool_use";
        }
        | {
            _meta?: { [key: string]: unknown };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: (...)
                        | (...);
                        sizes?: (...) | (...);
                        src: string;
                        theme?: (...) | (...) | (...);
                    }[];
                    mimeType?: string;
                    name: string;
                    size?: number;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: (...)[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: ...]: ... };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            toolUseId: string;
            type: "tool_result";
        }
        | (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            }
            | {
                _meta?: { [key: string]: unknown };
                id: string;
                input: { [key: string]: unknown };
                name: string;
                type: "tool_use";
            }
            | {
                _meta?: { [key: string]: unknown };
                content: (
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        description?: string;
                        icons?: (...)[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: ...]: ... };
                        annotations?: { audience?: ...; lastModified?: ...; priority?: ... };
                        resource:
                            | { _meta?: ...; mimeType?: ...; text: ...; uri: ... }
                            | { _meta?: ...; blob: ...; mimeType?: ...; uri: ... };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                toolUseId: string;
                type: "tool_result";
            }
        )[];
        model: string;
        role: "user"
        | "assistant";
        stopReason?: string;
        [key: string]: unknown;
    },
>
CreateMessageResult (single content block) or CreateMessageResultWithTools (array content, may include tool_use blocks) depending on whether tools was set
Throws
If the host rejects the request or does not support sampling

Throws
If the request times out or the connection is lost
Example: Simple completion
```
const result = await app.createSamplingMessage({
  messages: [
    {
      role: "user",
      content: { type: "text", text: "Summarize this in one line." },
    },
  ],
  maxTokens: 100,
});
console.log(result.content);
```
Example: Agentic loop with tools
```
if (!app.getHostCapabilities()?.sampling?.tools) return;

const result = await app.createSamplingMessage({
  messages,
  maxTokens: 1024,
  tools: [
    {
      name: "get_weather",
      description: "Get the current weather",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
      },
    },
  ],
});
if (result.stopReason === "toolUse") {
  // result.content may be an array containing tool_use blocks
}
```
See
- CreateMessageRequest from @modelcontextprotocol/sdk for the request type
- CreateMessageResult / CreateMessageResultWithTools from @modelcontextprotocol/sdk for result types
- Defined in src/app.ts:1425

downloadFile

downloadFile(
    params: {
        contents: (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                resource: | {
                    _meta?: { [key: string]: unknown };
                    mimeType?: string;
                    text: string;
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    blob: string;
                    mimeType?: string;
                    uri: string;
                };
                type: "resource";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ("user" | "assistant")[];
                    lastModified?: string;
                    priority?: number;
                };
                description?: string;
                icons?: {
                    mimeType?: string;
                    sizes?: string[];
                    src: string;
                    theme?: "light"
                    | "dark";
                }[];
                mimeType?: string;
                name: string;
                size?: number;
                title?: string;
                type: "resource_link";
                uri: string;
            }
        )[];
    },
    options?: RequestOptions,
): Promise<{ isError?: boolean; [key: string]: unknown }>
Request the host to download a file.

Since MCP Apps run in sandboxed iframes where direct downloads are blocked, this provides a host-mediated mechanism for file exports. The host will typically show a confirmation dialog before initiating the download.

Uses standard MCP resource types: EmbeddedResource for inline content and ResourceLink for content the host can fetch directly.
Parameters
- params: {
      contents: (
          | {
              _meta?: { [key: string]: unknown };
              annotations?: {
                  audience?: ("user" | "assistant")[];
                  lastModified?: string;
                  priority?: number;
              };
              resource: | {
                  _meta?: { [key: string]: unknown };
                  mimeType?: string;
                  text: string;
                  uri: string;
              }
              | {
                  _meta?: { [key: string]: unknown };
                  blob: string;
                  mimeType?: string;
                  uri: string;
              };
              type: "resource";
          }
          | {
              _meta?: { [key: string]: unknown };
              annotations?: {
                  audience?: ("user" | "assistant")[];
                  lastModified?: string;
                  priority?: number;
              };
              description?: string;
              icons?: {
                  mimeType?: string;
                  sizes?: string[];
                  src: string;
                  theme?: "light"
                  | "dark";
              }[];
              mimeType?: string;
              name: string;
              size?: number;
              title?: string;
              type: "resource_link";
              uri: string;
          }
      )[];
  }
  Resource contents to download
  - contents: (
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            resource: | {
                _meta?: { [key: string]: unknown };
                mimeType?: string;
                text: string;
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                blob: string;
                mimeType?: string;
                uri: string;
            };
            type: "resource";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            description?: string;
            icons?: {
                mimeType?: string;
                sizes?: string[];
                src: string;
                theme?: "light"
                | "dark";
            }[];
            mimeType?: string;
            name: string;
            size?: number;
            title?: string;
            type: "resource_link";
            uri: string;
        }
    )[]
    Description
    Resource contents to download — embedded (inline data) or linked (host fetches). Uses standard MCP resource types.
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<{ isError?: boolean; [key: string]: unknown }>
Result with isError: true if the host denied the request (e.g., user cancelled)
Throws
If the request times out or the connection is lost
Example: Download a JSON file (embedded text resource)
```
const data = JSON.stringify({ items: selectedItems }, null, 2);
const { isError } = await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///export.json",
      mimeType: "application/json",
      text: data,
    },
  }],
});
if (isError) {
  console.warn("Download denied or cancelled");
}
```
Example: Download binary content (embedded blob resource)
```
const { isError } = await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///image.png",
      mimeType: "image/png",
      blob: base64EncodedPng,
    },
  }],
});
```
Example: Download via resource link (host fetches)
```
const { isError } = await app.downloadFile({
  contents: [{
    type: "resource_link",
    uri: "https://api.example.com/reports/q4.pdf",
    name: "Q4 Report",
    mimeType: "application/pdf",
  }],
});
```
See
- McpUiDownloadFileRequest for request structure
- McpUiDownloadFileResult for result structure
- Defined in src/app.ts:1703

`Protected`getEventHandler

getEventHandler<K extends keyof AppEventMap>(
event: K,
): ((params: AppEventMap[K]) => void) | undefined
Get the singular on* handler for an event, or undefined if none is set. addEventListener listeners are not reflected here.
Type Parameters
- K extends keyof AppEventMap
Parameters
- event: K
Returns ((params: AppEventMap[K]) => void) | undefined
Inherited from ProtocolWithEvents.getEventHandler
- Defined in src/events.ts:151

getHostCapabilities

getHostCapabilities(): McpUiHostCapabilities | undefined
Get the host's capabilities discovered during initialization.

Returns the capabilities that the host advertised during the connect handshake. Returns undefined if called before connection is established.

Returns McpUiHostCapabilities | undefined
Host capabilities, or undefined if not yet connected
Example: Check host capabilities after connection
```
await app.connect();
if (app.getHostCapabilities()?.serverTools) {
  console.log("Host supports server tool calls");
}
```
See
- connect for the initialization handshake
- McpUiHostCapabilities for the capabilities structure
- Defined in src/app.ts:684

getHostContext

getHostContext(): McpUiHostContext | undefined
Get the host context discovered during initialization.

Returns the host context that was provided in the initialization response, including tool info, theme, locale, and other environment details. This context is automatically updated when the host sends ui/notifications/host-context-changed notifications.

Returns undefined if called before connection is established.

Returns McpUiHostContext | undefined
Host context, or undefined if not yet connected
Example: Access host context after connection
```
await app.connect(transport);
const context = app.getHostContext();
if (context?.theme === "dark") {
  document.body.classList.add("dark-theme");
}
if (context?.toolInfo) {
  console.log("Tool:", context.toolInfo.tool.name);
}
```
See
- connect for the initialization handshake
- onhostcontextchanged for context change notifications
- McpUiHostContext for the context structure
- Defined in src/app.ts:738

getHostVersion

getHostVersion(): | {
    description?: string;
    icons?: {
        mimeType?: string;
        sizes?: string[];
        src: string;
        theme?: "light"
        | "dark";
    }[];
    name: string;
    title?: string;
    version: string;
    websiteUrl?: string;
}
| undefined
Get the host's implementation info discovered during initialization.

Returns the host's name and version as advertised during the connect handshake. Returns undefined if called before connection is established.

Returns
    | {
        description?: string;
        icons?: {
            mimeType?: string;
            sizes?: string[];
            src: string;
            theme?: "light"
            | "dark";
        }[];
        name: string;
        title?: string;
        version: string;
        websiteUrl?: string;
    }
    | undefined
Host implementation info, or undefined if not yet connected
Example: Log host information after connection
```
await app.connect(transport);
const { name, version } = app.getHostVersion() ?? {};
console.log(`Connected to ${name} v${version}`);
```
See
connect for the initialization handshake
- Defined in src/app.ts:706

`Protected`getTask

getTask(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        taskId: string;
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        createdAt: string;
        lastUpdatedAt: string;
        pollInterval?: number;
        status: | "working"
        | "input_required"
        | "completed"
        | "failed"
        | "cancelled";
        statusMessage?: string;
        taskId: string;
        ttl: number
        | null;
    },
>
Experimental
Gets the current status of a task.

Use client.experimental.tasks.getTask() to access this method.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      taskId: string;
  }
- Optionaloptions: RequestOptions
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        createdAt: string;
        lastUpdatedAt: string;
        pollInterval?: number;
        status: | "working"
        | "input_required"
        | "completed"
        | "failed"
        | "cancelled";
        statusMessage?: string;
        taskId: string;
        ttl: number
        | null;
    },
>
Inherited from ProtocolWithEvents.getTask
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:357

`Protected`getTaskResult

getTaskResult<T extends AnySchema>(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        taskId: string;
    },
    resultSchema: T,
    options?: RequestOptions,
): Promise<SchemaOutput<T>>
Experimental
Retrieves the result of a completed task.

Use client.experimental.tasks.getTaskResult() to access this method.
Type Parameters
- T extends AnySchema
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      taskId: string;
  }
- resultSchema: T
- Optionaloptions: RequestOptions
Returns Promise<SchemaOutput<T>>
Inherited from ProtocolWithEvents.getTaskResult
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:363

listServerResources

listServerResources(
    params?: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        cursor?: string;
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        nextCursor?: string;
        resources: {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            description?: string;
            icons?: {
                mimeType?: string;
                sizes?: string[];
                src: string;
                theme?: "light"
                | "dark";
            }[];
            mimeType?: string;
            name: string;
            size?: number;
            title?: string;
            uri: string;
        }[];
        [key: string]: unknown;
    },
>
List available resources from the originating MCP server (proxied through the host).

Apps can list resources to discover what content is available on the MCP server. This enables dynamic resource discovery and building resource browsers or pickers. The host proxies the request to the actual MCP server and returns the resource list.

Results may be paginated using the cursor parameter for servers with many resources.
Parameters
- Optionalparams: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      cursor?: string;
  }
  Optional parameters (omit for all resources, or { cursor } for pagination)
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        nextCursor?: string;
        resources: {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: ("user" | "assistant")[];
                lastModified?: string;
                priority?: number;
            };
            description?: string;
            icons?: {
                mimeType?: string;
                sizes?: string[];
                src: string;
                theme?: "light"
                | "dark";
            }[];
            mimeType?: string;
            name: string;
            size?: number;
            title?: string;
            uri: string;
        }[];
        [key: string]: unknown;
    },
>
List of resources with their URIs, names, descriptions, mimeTypes, and optional pagination cursor
Throws
If the request times out or the connection is lost

Throws
If the host rejects the request
Example: Discover available videos and build a picker UI
```
try {
  const result = await app.listServerResources();
  const videoResources = result.resources.filter((r) =>
    r.mimeType?.startsWith("video/"),
  );
  videoResources.forEach((resource) => {
    const option = document.createElement("option");
    option.value = resource.uri;
    option.textContent = resource.description || resource.name;
    selectElement.appendChild(option);
  });
} catch (error) {
  console.error("Failed to list resources:", error);
}
```
See
readServerResource to read a specific resource
- Defined in src/app.ts:1348

`Protected`listTasks

listTasks(
    params?: { cursor?: string },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        nextCursor?: string;
        tasks: {
            createdAt: string;
            lastUpdatedAt: string;
            pollInterval?: number;
            status: | "working"
            | "input_required"
            | "completed"
            | "failed"
            | "cancelled";
            statusMessage?: string;
            taskId: string;
            ttl: number
            | null;
        }[];
        [key: string]: unknown;
    },
>
Experimental
Lists tasks, optionally starting from a pagination cursor.

Use client.experimental.tasks.listTasks() to access this method.
Parameters
- Optionalparams: { cursor?: string }
- Optionaloptions: RequestOptions
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        nextCursor?: string;
        tasks: {
            createdAt: string;
            lastUpdatedAt: string;
            pollInterval?: number;
            status: | "working"
            | "input_required"
            | "completed"
            | "failed"
            | "cancelled";
            statusMessage?: string;
            taskId: string;
            ttl: number
            | null;
        }[];
        [key: string]: unknown;
    },
>
Inherited from ProtocolWithEvents.listTasks
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:369

notification

notification(
notification: AppNotification,
options?: NotificationOptions,
): Promise<void>
Emits a notification, which is a one-way message that does not expect a response.
Parameters
- notification: AppNotification
- Optionaloptions: NotificationOptions
Returns Promise<void>
Inherited from ProtocolWithEvents.notification
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:383

`Protected`onEventDispatch

onEventDispatch<K extends keyof AppEventMap>(
event: K,
params: AppEventMap[K],
): void
Called once per incoming notification, before any handlers or listeners fire. Subclasses may override to perform side effects such as merging notification params into cached state.
Type Parameters
- K extends keyof AppEventMap
Parameters
- event: K
- params: AppEventMap[K]
Returns void
Overrides ProtocolWithEvents.onEventDispatch
- Defined in src/app.ts:446

openLink

openLink(
params: { url: string },
options?: RequestOptions,
): Promise<{ isError?: boolean; [key: string]: unknown }>
Request the host to open an external URL in the default browser.

The host may deny this request based on user preferences or security policy. Apps should handle rejection gracefully by checking result.isError.
Parameters
- params: { url: string }
  URL to open
  - url: string
    Description
    URL to open in the host's browser
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<{ isError?: boolean; [key: string]: unknown }>
Result with isError: true if the host denied the request (e.g., blocked domain, user cancelled)
Throws
If the request times out or the connection is lost
Example: Open documentation link
```
const { isError } = await app.openLink({ url: "https://docs.example.com" });
if (isError) {
  // Host denied the request (e.g., blocked domain, user cancelled)
  // Optionally show fallback: display URL for manual copy
  console.warn("Link request denied");
}
```
See
- McpUiOpenLinkRequest for request structure
- McpUiOpenLinkResult for result structure
- Defined in src/app.ts:1625

readServerResource

readServerResource(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        uri: string;
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        contents: (
            | {
                _meta?: { [key: string]: unknown };
                mimeType?: string;
                text: string;
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                blob: string;
                mimeType?: string;
                uri: string;
            }
        )[];
        [key: string]: unknown;
    },
>
Read a resource from the originating MCP server (proxied through the host).

Apps can read resources to access files, data, or other content provided by the MCP server. Resources are identified by URI (e.g., file:///path/to/file or custom schemes like videos://bunny-1mb). The host proxies the request to the actual MCP server and returns the resource content.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      uri: string;
  }
  Resource URI to read
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        contents: (
            | {
                _meta?: { [key: string]: unknown };
                mimeType?: string;
                text: string;
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                blob: string;
                mimeType?: string;
                uri: string;
            }
        )[];
        [key: string]: unknown;
    },
>
Resource content with URI, name, description, mimeType, and contents array
Throws
If the resource does not exist on the server

Throws
If the request times out or the connection is lost

Throws
If the host rejects the request
Example: Read a video resource and play it
```
try {
  const result = await app.readServerResource({
    uri: "videos://bunny-1mb",
  });
  const content = result.contents[0];
  if (content && "blob" in content) {
    const binary = Uint8Array.from(atob(content.blob), (c) =>
      c.charCodeAt(0),
    );
    const url = URL.createObjectURL(
      new Blob([binary], { type: content.mimeType || "video/mp4" }),
    );
    videoElement.src = url;
    videoElement.play();
  }
} catch (error) {
  console.error("Failed to read resource:", error);
}
```
See
listServerResources to discover available resources
- Defined in src/app.ts:1300

registerTool

registerTool<
    OutputArgs extends
        StandardSchemaV1<unknown, unknown>
        | undefined = undefined,
    InputArgs extends
        StandardSchemaV1<unknown, unknown>
        | undefined = undefined,
>(
    name: string,
    config: {
        _meta?: Record<string, unknown>;
        annotations?: {
            destructiveHint?: boolean;
            idempotentHint?: boolean;
            openWorldHint?: boolean;
            readOnlyHint?: boolean;
            title?: string;
        };
        description?: string;
        inputSchema?: InputArgs;
        outputSchema?: OutputArgs;
        title?: string;
    },
    cb: AppToolCallback<InputArgs, OutputArgs>,
): RegisteredAppTool
Type Parameters
- OutputArgs extends StandardSchemaV1<unknown, unknown> | undefined = undefined
- InputArgs extends StandardSchemaV1<unknown, unknown> | undefined = undefined
Parameters
- name: string
- config: {
      _meta?: Record<string, unknown>;
      annotations?: {
          destructiveHint?: boolean;
          idempotentHint?: boolean;
          openWorldHint?: boolean;
          readOnlyHint?: boolean;
          title?: string;
      };
      description?: string;
      inputSchema?: InputArgs;
      outputSchema?: OutputArgs;
      title?: string;
  }
- cb: AppToolCallback<InputArgs, OutputArgs>
Returns RegisteredAppTool
- Defined in src/app.ts:502

removeEventListener

removeEventListener<K extends keyof AppEventMap>(
event: K,
handler: (params: AppEventMap[K]) => void,
): void
Remove a previously registered event listener. The dispatcher stays registered even if the listener array becomes empty; future notifications simply have no listeners to call.
Type Parameters
- K extends keyof AppEventMap
Parameters
- event: K
- handler: (params: AppEventMap[K]) => void
Returns void
Inherited from ProtocolWithEvents.removeEventListener
- Defined in src/events.ts:184

removeNotificationHandler

removeNotificationHandler(method: string): void
Removes the notification handler for the given method.
Parameters
- method: string
Returns void
Inherited from ProtocolWithEvents.removeNotificationHandler
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:407

removeRequestHandler

removeRequestHandler(method: string): void
Removes the request handler for the given method.
Parameters
- method: string
Returns void
Inherited from ProtocolWithEvents.removeRequestHandler
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:393

request

request<T extends AnySchema>(
    request: AppRequest,
    resultSchema: T,
    options?: RequestOptions,
): Promise<SchemaOutput<T>>
Sends a request and waits for a response.

Do not use this method to emit notifications! Use notification() instead.
Type Parameters
- T extends AnySchema
Parameters
- request: AppRequest
- resultSchema: T
- Optionaloptions: RequestOptions
Returns Promise<SchemaOutput<T>>
Inherited from ProtocolWithEvents.request
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:351

requestDisplayMode

requestDisplayMode(
    params: { mode: McpUiDisplayMode },
    options?: RequestOptions,
): Promise<
    { mode: "inline"
    | "fullscreen"
    | "pip"; [key: string]: unknown },
>
Request a change to the display mode.

Requests the host to change the UI container to the specified display mode (e.g., "inline", "fullscreen", "pip"). The host will respond with the actual display mode that was set, which may differ from the requested mode if the requested mode is not available (check availableDisplayModes in host context).
Parameters
- params: { mode: McpUiDisplayMode }
  The display mode being requested
  - mode: McpUiDisplayMode
    Description
    The display mode being requested.
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<{ mode: "inline" | "fullscreen" | "pip"; [key: string]: unknown }>
Result containing the actual display mode that was set
Example: Toggle display mode
```
const container = document.getElementById("main")!;
const ctx = app.getHostContext();
const newMode = ctx?.displayMode === "inline" ? "fullscreen" : "inline";
if (ctx?.availableDisplayModes?.includes(newMode)) {
  const result = await app.requestDisplayMode({ mode: newMode });
  container.classList.toggle("fullscreen", result.mode === "fullscreen");
}
```
See
- McpUiRequestDisplayModeRequest for request structure
- McpUiHostContext for checking availableDisplayModes
- Defined in src/app.ts:1788

`Protected`requestStream

requestStream<T extends AnySchema>(
    request: AppRequest,
    resultSchema: T,
    options?: RequestOptions,
): AsyncGenerator<ResponseMessage<SchemaOutput<T>>, void, void>
Experimental
Sends a request and returns an AsyncGenerator that yields response messages. The generator is guaranteed to end with either a 'result' or 'error' message.
Type Parameters
- T extends AnySchema
Parameters
- request: AppRequest
- resultSchema: T
- Optionaloptions: RequestOptions
Returns AsyncGenerator<ResponseMessage<SchemaOutput<T>>, void, void>
Example
```
const stream = protocol.requestStream(request, resultSchema, options);
for await (const message of stream) {
  switch (message.type) {
    case 'taskCreated':
      console.log('Task created:', message.task.taskId);
      break;
    case 'taskStatus':
      console.log('Task status:', message.task.status);
      break;
    case 'result':
      console.log('Final result:', message.result);
      break;
    case 'error':
      console.error('Error:', message.error);
      break;
  }
}
```
Use client.experimental.tasks.requestStream() to access this method.
Inherited from ProtocolWithEvents.requestStream
- Defined in node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.d.ts:345

requestTeardown

requestTeardown(params?: {} | undefined): Promise<void>
Request the host to tear down this app.

Apps call this method to request that the host tear them down. The host decides whether to proceed - if approved, the host will send ui/resource-teardown to allow the app to perform gracefull termination before being unmounted. This piggybacks on the existing teardown mechanism, ensuring the app only needs a single shutdown procedure (via onteardown) regardless of whether the teardown was initiated by the app or the host.

This is a fire-and-forget notification - no response is expected. If the host approves, the app will receive a ui/resource-teardown request via the onteardown handler to persist unsaved state.
Parameters
- params: {} | undefined = {}
  Empty params object (reserved for future use)
Returns Promise<void>
Promise that resolves when the notification is sent
Example: App-initiated teardown after user action
```
// User clicks "Done" button in the app
async function handleDoneClick() {
  // Request the host to tear down the app
  await app.requestTeardown();
  // If host approves, onteardown handler will be called for termination
}

// Set up teardown handler (called for both app-initiated and host-initiated teardown)
app.onteardown = async () => {
  await saveState();
  closeConnections();
  return {};
};
```
See
- McpUiRequestTeardownNotification for notification structure
- onteardown for the graceful termination handler
- Defined in src/app.ts:1755

sendLog

sendLog(
    params: {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        data: unknown;
        level: | "error"
        | "alert"
        | "debug"
        | "info"
        | "notice"
        | "warning"
        | "critical"
        | "emergency";
        logger?: string;
    },
): Promise<void>
Send log messages to the host for debugging and telemetry.

Logs are not added to the conversation but may be recorded by the host for debugging purposes.
Parameters
- params: {
      _meta?: {
          "io.modelcontextprotocol/related-task"?: { taskId: string };
          progressToken?: string | number;
          [key: string]: unknown;
      };
      data: unknown;
      level: | "error"
      | "alert"
      | "debug"
      | "info"
      | "notice"
      | "warning"
      | "critical"
      | "emergency";
      logger?: string;
  }
  Log level and message
Returns Promise<void>
Promise that resolves when the log notification is sent
Example: Log app state for debugging
```
app.sendLog({
  level: "info",
  data: "Weather data refreshed",
  logger: "WeatherApp",
});
```
- Defined in src/app.ts:1525

sendMessage

sendMessage(
params: { content: ContentBlock[]; role: "user" },
options?: RequestOptions,
): Promise<{ isError?: boolean; [key: string]: unknown }>
Send a message to the host's chat interface.

Enables the app to add messages to the conversation thread. Useful for user-initiated messages or app-to-conversation communication.
Parameters
- params: { content: ContentBlock[]; role: "user" }
  Message role and content
  - content: ContentBlock[]
    Description
    Message content blocks (text, image, etc.).
  - role: "user"
    Description
    Message role, currently only "user" is supported.
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<{ isError?: boolean; [key: string]: unknown }>
Result with optional isError flag indicating host rejection
Throws
If the request times out or the connection is lost
Example: Send a text message from user interaction
```
try {
  const result = await app.sendMessage({
    role: "user",
    content: [{ type: "text", text: "Show me details for item #42" }],
  });
  if (result.isError) {
    console.error("Host rejected the message");
    // Handle rejection appropriately for your app
  }
} catch (error) {
  console.error("Failed to send message:", error);
  // Handle transport/protocol error
}
```
Example: Send follow-up message after offloading large data to model context
```
const markdown = `---
word-count: ${fullTranscript.split(/\s+/).length}
speaker-names: ${speakerNames.join(", ")}
---

${fullTranscript}`;

// Offload long transcript to model context
await app.updateModelContext({ content: [{ type: "text", text: markdown }] });

// Send brief trigger message
await app.sendMessage({
  role: "user",
  content: [{ type: "text", text: "Summarize the key points" }],
});
```
See
McpUiMessageRequest for request structure
- Defined in src/app.ts:1494

sendSizeChanged

sendSizeChanged(params: { height?: number; width?: number }): Promise<void>
Notify the host of UI size changes.

Apps can manually report size changes to help the host adjust the container. If autoResize is enabled (default), this is called automatically.
Parameters
- params: { height?: number; width?: number }
  New width and height in pixels
  - Optionalheight?: number
    Description
    New height in pixels.
  - Optionalwidth?: number
    Description
    New width in pixels.
Returns Promise<void>
Promise that resolves when the notification is sent
Example: Manually notify host of size change
```
app.sendSizeChanged({
  width: 400,
  height: 600,
});
```
See
McpUiSizeChangedNotification for notification structure
- Defined in src/app.ts:1823

sendToolListChanged

sendToolListChanged(
    params?:
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
        }
        | undefined,
): Promise<void>
Parameters
- params:
      | {
          _meta?: {
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              progressToken?: string | number;
              [key: string]: unknown;
          };
      }
      | undefined = {}
Returns Promise<void>
- Defined in src/app.ts:654

`Protected`setEventHandler

setEventHandler<K extends keyof AppEventMap>(
event: K,
handler: ((params: AppEventMap[K]) => void) | undefined,
): void
Set or clear the singular on* handler for an event.

Replace semantics — like the DOM's el.onclick = fn. Assigning undefined clears the handler without affecting addEventListener listeners.
Type Parameters
- K extends keyof AppEventMap
Parameters
- event: K
- handler: ((params: AppEventMap[K]) => void) | undefined
Returns void
Overrides ProtocolWithEvents.setEventHandler
- Defined in src/app.ts:430

setupSizeChangedNotifications

setupSizeChangedNotifications(): () => void
Set up automatic size change notifications using ResizeObserver.

Observes both document.documentElement and document.body for size changes and automatically sends ui/notifications/size-changed notifications to the host. The notifications are debounced using requestAnimationFrame to avoid duplicates.

Note: This method is automatically called by connect() if the autoResize option is true (default). You typically don't need to call this manually unless you disabled autoResize and want to enable it later.

Returns () => void
Cleanup function to disconnect the observer
Example: Manual setup for custom scenarios
```
const app = new App(
  { name: "MyApp", version: "1.0.0" },
  {},
  { autoResize: false },
);
await app.connect(transport);

// Later, enable auto-resize manually
const cleanup = app.setupSizeChangedNotifications();

// Clean up when done
cleanup();
```
- Defined in src/app.ts:1859

updateModelContext

updateModelContext(
    params: {
        content?: ContentBlock[];
        structuredContent?: Record<string, unknown>;
    },
    options?: RequestOptions,
): Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
    },
>
Update the host's model context with app state.

Context updates are intended to be available to the model in future turns, without triggering an immediate model response (unlike sendMessage).

The host will typically defer sending the context to the model until the next user message — either from the actual user or via sendMessage. Only the last update is sent; each call overwrites any previous context.
Parameters
- params: { content?: ContentBlock[]; structuredContent?: Record<string, unknown> }
  Context content and/or structured content
  - Optionalcontent?: ContentBlock[]
    Description
    Context content blocks (text, image, etc.).
  - OptionalstructuredContent?: Record<string, unknown>
    Description
    Structured content for machine-readable context data.
- Optionaloptions: RequestOptions
  Request options (timeout, etc.)
Returns Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
    },
>
Promise that resolves when the context update is acknowledged
Throws
If the host rejects the context update (e.g., unsupported content type)

Throws
If the request times out or the connection is lost
Example: Update model context with current app state
```
const markdown = `---
item-count: ${itemList.length}
total-cost: ${totalCost}
currency: ${currency}
---

User is viewing their shopping cart with ${itemList.length} items selected:

${itemList.map((item) => `- ${item}`).join("\n")}`;

await app.updateModelContext({
  content: [{ type: "text", text: markdown }],
});
```
Example: Report runtime error to model
```
try {
  const _stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  // ... use _stream for transcription
} catch (err) {
  // Inform the model that the app is in a degraded state
  await app.updateModelContext({
    content: [
      {
        type: "text",
        text: "Error: transcription unavailable",
      },
    ],
  });
}
```
- Defined in src/app.ts:1585

`Protected`warnIfRequestHandlerReplaced

warnIfRequestHandlerReplaced(
    name: string,
    previous: unknown,
    next: unknown,
): void
Warn if a request handler on* setter is replacing a previously-set handler. Call from each request setter before updating the backing field.
Parameters
- name: string
- previous: unknown
- next: unknown
Returns void
Inherited from ProtocolWithEvents.warnIfRequestHandlerReplaced
- Defined in src/events.ts:241

Properties

`Protected` `Readonly`eventSchemas

eventSchemas: {
    hostcontextchanged: ZodObject<
        {
            method: ZodLiteral<"ui/notifications/host-context-changed">;
            params: ZodObject<
                {
                    availableDisplayModes: ZodOptional<
                        ZodArray<
                            ZodUnion<
                                readonly [
                                    ZodLiteral<"inline">,
                                    ZodLiteral<"fullscreen">,
                                    ZodLiteral<"pip">,
                                ],
                            >,
                        >,
                    >;
                    containerDimensions: ZodOptional<
                        ZodIntersection<
                            ZodUnion<
                                readonly [
                                    ZodObject<{ height: ... }, $strip>,
                                    ZodObject<{ maxHeight: ... }, $strip>,
                                ],
                            >,
                            ZodUnion<
                                readonly [
                                    ZodObject<{ width: ... }, $strip>,
                                    ZodObject<{ maxWidth: ... }, $strip>,
                                ],
                            >,
                        >,
                    >;
                    deviceCapabilities: ZodOptional<
                        ZodObject<
                            { hover: ZodOptional<ZodBoolean>; touch: ZodOptional<ZodBoolean> },
                            $strip,
                        >,
                    >;
                    displayMode: ZodOptional<
                        ZodUnion<
                            readonly [
                                ZodLiteral<"inline">,
                                ZodLiteral<"fullscreen">,
                                ZodLiteral<"pip">,
                            ],
                        >,
                    >;
                    locale: ZodOptional<ZodString>;
                    platform: ZodOptional<
                        ZodUnion<
                            readonly [
                                ZodLiteral<"web">,
                                ZodLiteral<"desktop">,
                                ZodLiteral<"mobile">,
                            ],
                        >,
                    >;
                    safeAreaInsets: ZodOptional<
                        ZodObject<
                            {
                                bottom: ZodNumber;
                                left: ZodNumber;
                                right: ZodNumber;
                                top: ZodNumber;
                            },
                            $strip,
                        >,
                    >;
                    styles: ZodOptional<
                        ZodObject<
                            {
                                css: ZodOptional<ZodObject<{ fonts: ... }, $strip>>;
                                variables: ZodOptional<ZodRecord<ZodUnion<(...)>, ZodUnion<(...)>>>;
                            },
                            $strip,
                        >,
                    >;
                    theme: ZodOptional<
                        ZodUnion<readonly [ZodLiteral<"light">, ZodLiteral<"dark">]>,
                    >;
                    timeZone: ZodOptional<ZodString>;
                    toolInfo: ZodOptional<
                        ZodObject<
                            {
                                id: ZodOptional<ZodUnion<readonly [(...), (...)]>>;
                                tool: ZodObject<
                                    {
                                        _meta: ZodOptional<(...)>;
                                        annotations: ZodOptional<(...)>;
                                        description: ZodOptional<(...)>;
                                        execution: ZodOptional<(...)>;
                                        icons: ZodOptional<(...)>;
                                        inputSchema: ZodObject<(...), (...)>;
                                        name: ZodString;
                                        outputSchema: ZodOptional<(...)>;
                                        title: ZodOptional<(...)>;
                                    },
                                    $strip,
                                >;
                            },
                            $strip,
                        >,
                    >;
                    userAgent: ZodOptional<ZodString>;
                },
                $loose,
            >;
        },
        $strip,
    >;
    toolcancelled: ZodObject<
        {
            method: ZodLiteral<"ui/notifications/tool-cancelled">;
            params: ZodObject<{ reason: ZodOptional<ZodString> }, $strip>;
        },
        $strip,
    >;
    toolinput: ZodObject<
        {
            method: ZodLiteral<"ui/notifications/tool-input">;
            params: ZodObject<
                { arguments: ZodOptional<ZodRecord<ZodString, ZodUnknown>> },
                $strip,
            >;
        },
        $strip,
    >;
    toolinputpartial: ZodObject<
        {
            method: ZodLiteral<"ui/notifications/tool-input-partial">;
            params: ZodObject<
                { arguments: ZodOptional<ZodRecord<ZodString, ZodUnknown>> },
                $strip,
            >;
        },
        $strip,
    >;
    toolresult: ZodObject<
        {
            method: ZodLiteral<"ui/notifications/tool-result">;
            params: ZodObject<
                {
                    _meta: ZodOptional<
                        ZodObject<
                            {
                                "io.modelcontextprotocol/related-task": ZodOptional<
                                    ZodObject<{ taskId: ... }, $strip>,
                                >;
                                progressToken: ZodOptional<ZodUnion<readonly [(...), (...)]>>;
                            },
                            $loose,
                        >,
                    >;
                    content: ZodDefault<
                        ZodArray<
                            ZodUnion<
                                readonly [
                                    ZodObject<
                                        { _meta: ...; annotations: ...; text: ...; type: ... },
                                        $strip,
                                    >,
                                    ZodObject<
                                        {
                                            _meta: ...;
                                            annotations: ...;
                                            data: ...;
                                            mimeType: ...;
                                            type: ...;
                                        },
                                        $strip,
                                    >,
                                    ZodObject<
                                        {
                                            _meta: ...;
                                            annotations: ...;
                                            data: ...;
                                            mimeType: ...;
                                            type: ...;
                                        },
                                        $strip,
                                    >,
                                    ZodObject<
                                        {
                                            _meta: ...;
                                            annotations: ...;
                                            description: ...;
                                            icons: ...;
                                            mimeType: ...;
                                            name: ...;
                                            size: ...;
                                            title: ...;
                                            type: ...;
                                            uri: ...;
                                        },
                                        $strip,
                                    >,
                                    ZodObject<
                                        { _meta: ...; annotations: ...; resource: ...; type: ... },
                                        $strip,
                                    >,
                                ],
                            >,
                        >,
                    >;
                    isError: ZodOptional<ZodBoolean>;
                    structuredContent: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
                },
                $loose,
            >;
        },
        $strip,
    >;
} = ...

Event name → notification schema. Subclasses populate this so that the event system can lazily register a dispatcher with the correct schema on first use.

`Optional`fallbackNotificationHandler

fallbackNotificationHandler?: (
    notification: {
        method: string;
        params?: {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            [key: string]: unknown;
        };
    },
) => Promise<void>

A handler to invoke for any notification types that do not have their own handler installed.

`Optional`fallbackRequestHandler

fallbackRequestHandler?: (
    request: {
        id: string | number;
        jsonrpc: "2.0";
        method: string;
        params?: {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            [key: string]: unknown;
        };
    },
    extra: RequestHandlerExtra<AppRequest, AppNotification>,
) => Promise<AppResult>

A handler to invoke for any request types that do not have their own handler installed.

`Optional`onclose

onclose?: () => void

Callback for when the connection is closed for any reason.

This is invoked when close() is called as well.

`Optional`onerror

onerror?: (error: Error) => void

Callback for when an error occurs.

Note that errors are not necessarily fatal; they are used for reporting any kind of exceptional condition out of band.

`Protected`replaceRequestHandler

replaceRequestHandler: <T extends AnyObjectSchema>(
    requestSchema: T,
    handler: (
        request: SchemaOutput<T>,
        extra: RequestHandlerExtra<AppRequest, AppNotification>,
    ) => AppResult | Promise<AppResult>,
) => void = ...

Replace a request handler, bypassing double-set protection. Used by on* request-handler setters that need replace semantics.

Type Declaration

- <T extends AnyObjectSchema>(
      requestSchema: T,
      handler: (
          request: SchemaOutput<T>,
          extra: RequestHandlerExtra<AppRequest, AppNotification>,
      ) => AppResult | Promise<AppResult>,
  ): void
- Registers a handler to invoke when this protocol object receives a request with the given method.
  
  Note that this will replace any previous request handler for the same method.
  Type Parameters
  - T extends AnyObjectSchema
  Parameters
  - requestSchema: T
  - handler: (
    request: SchemaOutput<T>,
    extra: RequestHandlerExtra<AppRequest, AppNotification>,
    ) => AppResult | Promise<AppResult>
  Returns void

sendOpenLink

sendOpenLink: (
params: { url: string },
options?: RequestOptions,
) => Promise<{ isError?: boolean; [key: string]: unknown }> = ...

Type Declaration

- (
  params: { url: string },
  options?: RequestOptions,
  ): Promise<{ isError?: boolean; [key: string]: unknown }>
- Request the host to open an external URL in the default browser.
  
  The host may deny this request based on user preferences or security policy. Apps should handle rejection gracefully by checking result.isError.
  Parameters
  - params: { url: string }
    URL to open
    - url: string
      Description
      URL to open in the host's browser
  - Optionaloptions: RequestOptions
    Request options (timeout, etc.)
  Returns Promise<{ isError?: boolean; [key: string]: unknown }>
  Result with isError: true if the host denied the request (e.g., blocked domain, user cancelled)
  Throws
  If the request times out or the connection is lost
  Example: Open documentation link
```
const { isError } = await app.openLink({ url: "https://docs.example.com" });
if (isError) {
  // Host denied the request (e.g., blocked domain, user cancelled)
  // Optionally show fallback: display URL for manual copy
  console.warn("Link request denied");
}
```
  See
  - McpUiOpenLinkRequest for request structure
  - McpUiOpenLinkResult for result structure

Deprecated

Use openLink instead

setNotificationHandler

setNotificationHandler: <T extends AnyObjectSchema>(
notificationSchema: T,
handler: (notification: SchemaOutput<T>) => void | Promise<void>,
) => void = ...

Registers a notification handler. Throws if a handler for the same method has already been registered — use the on* setter (replace semantics) or addEventListener (multi-listener) for mapped events.

Type Declaration

- <T extends AnyObjectSchema>(
  notificationSchema: T,
  handler: (notification: SchemaOutput<T>) => void | Promise<void>,
  ): void
- Registers a handler to invoke when this protocol object receives a notification with the given method.
  
  Note that this will replace any previous notification handler for the same method.
  Type Parameters
  - T extends AnyObjectSchema
  Parameters
  - notificationSchema: T
  - handler: (notification: SchemaOutput<T>) => void | Promise<void>
  Returns void

Throws

if a handler for this method is already registered.

setRequestHandler

setRequestHandler: <T extends AnyObjectSchema>(
    requestSchema: T,
    handler: (
        request: SchemaOutput<T>,
        extra: RequestHandlerExtra<AppRequest, AppNotification>,
    ) => AppResult | Promise<AppResult>,
) => void = ...

Registers a request handler. Throws if a handler for the same method has already been registered — use the on* setter (replace semantics) or addEventListener (multi-listener) for notification events.

Type Declaration

- <T extends AnyObjectSchema>(
      requestSchema: T,
      handler: (
          request: SchemaOutput<T>,
          extra: RequestHandlerExtra<AppRequest, AppNotification>,
      ) => AppResult | Promise<AppResult>,
  ): void
- Registers a handler to invoke when this protocol object receives a request with the given method.
  
  Note that this will replace any previous request handler for the same method.
  Type Parameters
  - T extends AnyObjectSchema
  Parameters
  - requestSchema: T
  - handler: (
    request: SchemaOutput<T>,
    extra: RequestHandlerExtra<AppRequest, AppNotification>,
    ) => AppResult | Promise<AppResult>
  Returns void

Throws

if a handler for this method is already registered.

Sunbelt Computer Software

PL/B Language Development and Support

Class App

Architecture

Lifecycle

Inherited Methods

See

Notification Setters (DOM-model on* handlers)

Example: Basic usage with PostMessageTransport

Hierarchy (View Summary)

Index

Accessors

Constructors

Methods

Properties

Accessors

oncalltool

Parameters

Returns void

onhostcontextchanged

Returns ((params: McpUiHostContext) => void) | undefined

Example: Respond to theme changes

Deprecated

See

Parameters

Returns void

onlisttools

Parameters

Returns void

onteardown

Returns | ( ( params: {}, extra: RequestHandlerExtra, ) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult> ) | undefined

Parameters

Returns void

ontoolcancelled

Returns ((params: { reason?: string }) => void) | undefined

Example: Handle tool cancellation

Deprecated

See

Parameters

Returns void

ontoolinput

Returns ((params: { arguments?: Record<string, unknown> }) => void) | undefined

Example

Deprecated

See

Parameters

Returns void

ontoolinputpartial

Returns ((params: { arguments?: Record<string, unknown> }) => void) | undefined

Example: Progressive rendering of tool arguments

Deprecated

See

Parameters

Returns void

ontoolresult

Example: Display tool execution results

Deprecated

See

Parameters

Returns void

transport

Returns Transport | undefined

Constructors

constructor

Parameters

Returns App

Example

Methods

addEventListener

Type Parameters

Parameters

Returns void

assertCanSetRequestHandler

Parameters

Returns void

assertCapabilityForMethod

Parameters

Returns void

assertNotificationCapability

Parameters

Notification Setters (DOM-model `on*` handlers)

Returns
| (
(
params: {},
extra: RequestHandlerExtra,
) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>
)
| undefined

`Protected`assertTaskCapability

`Protected`assertTaskHandlerCapability

`Protected`cancelTask

`Protected`getEventHandler

Returns
| {
description?: string;
icons?: {
mimeType?: string;
sizes?: string[];
src: string;
theme?: "light"
| "dark";
}[];
name: string;
title?: string;
version: string;
websiteUrl?: string;
}
| undefined