MCP Apps ontoolinputpartial - Streaming Partial Tool Arguments

MCP Apps SDK

import { App } from "@modelcontextprotocol/ext-apps";

Overview

The ontoolinputpartial notification handler receives best-effort tool arguments while the host is still generating a tool call. Use it to show a preview before the complete input arrives. The host may recover incomplete JSON by closing open brackets or braces before sending each notification. The resulting arguments object is valid JSON, but fields can be missing, truncated, replaced, or removed by a later notification. Like all notification handlers, ontoolinputpartial should be registered before calling connect().

Use partial input only for preview UI. Do not save data, submit forms, call tools, or start any other operation that depends on complete arguments.

Event Order

For one tool call, the host sends events in this order:

Zero or more ui/notifications/tool-input-partial notifications while arguments stream.
At most one ui/notifications/tool-input notification with the complete arguments. The host stops sending partials after this event.
A ui/notifications/tool-result or ui/notifications/tool-cancelled notification.

An app may ignore partial notifications. Always support the complete input event because hosts do not have to stream partials.

Signature

app.ontoolinputpartial = (params) => void;

Parameters

Record<string, unknown>

Best-effort tool arguments recovered from incomplete JSON. Fields may be missing or change between notifications.

Usage

Basic preview rendering

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

const codePreview = document.querySelector<HTMLPreElement>("#code-preview")!;

app.ontoolinputpartial = (params) => {
  codePreview.textContent = typeof params.arguments?.code === "string"
    ? params.arguments.code
    : "";
};

await app.connect();

Progressive rendering with a final state

Combine ontoolinputpartial for live preview with ontoolinput for the finalized result:

const preview = document.querySelector<HTMLElement>("#preview")!;

app.ontoolinputpartial = (params) => {
  const markdown = typeof params.arguments?.content === "string"
    ? params.arguments.content
    : "";
  preview.textContent = markdown;
  preview.dataset.state = "streaming";
};

app.ontoolinput = (params) => {
  const markdown = typeof params.arguments?.content === "string"
    ? params.arguments.content
    : "";
  preview.textContent = markdown;
  preview.dataset.state = "complete";
};

app.ontoolcancelled = () => {
  preview.textContent = "Tool call cancelled";
  preview.dataset.state = "cancelled";
};

Partial arguments come from model-generated input, so treat them as untrusted. Render text with textContent or framework escaping. If you render Markdown or HTML, sanitize it before assigning it to innerHTML.

Using with the sunpeak framework

The sunpeak framework provides the useToolData hook. Partial and complete arguments use separate fields so preview state cannot overwrite finalized input.

import { useToolData } from "sunpeak";

interface DraftInput {
  content?: string;
}

function Preview() {
  const { inputPartial, input, isCancelled } = useToolData<DraftInput>();
  const currentInput = inputPartial ?? input;

  if (isCancelled) return <p>Tool call cancelled</p>;

  return (
    <pre data-state={inputPartial ? "streaming" : input ? "complete" : "waiting"}>
      {currentInput?.content ?? "Waiting for input..."}
    </pre>
  );
}

inputPartial updates as partial notifications arrive. When the complete input arrives, sunpeak sets input, clears inputPartial, and keeps the final arguments available for the rest of the tool lifecycle.

Test Streaming Input Locally

Run sunpeak dev, open Tool Input in the inspector sidebar, edit the JSON, and click Send as Partial (Streaming). Check that your View:

Renders missing and incomplete fields without throwing.
Does not trigger tool calls or other side effects from a partial event.
Replaces the preview when complete input or cancellation arrives.

See Inspector Controls for the rest of the tool lifecycle controls.

Event Handlers overview for all notification and request handlers
MCP App lifecycle for event ordering from initialization through teardown
MCP Apps security for rendering untrusted tool data

Overview

App

MCP

React

Server

Styling

Types

MCP Apps ontoolinputpartial - Streaming Partial Tool Arguments

Overview

Event Order

Signature

Parameters

Usage

Basic preview rendering

Progressive rendering with a final state

Using with the sunpeak framework

Test Streaming Input Locally

​Overview

​Event Order

​Signature

​Parameters

​Usage

​Basic preview rendering

​Progressive rendering with a final state

​Using with the sunpeak framework

​Test Streaming Input Locally

​Related

Overview

Event Order

Signature

Parameters

Usage

Basic preview rendering

Progressive rendering with a final state

Using with the sunpeak framework

Test Streaming Input Locally

Related