MCP Apps Requests - View-to-Host API

MCP Apps SDK

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

Overview

The App class provides methods for the View to make requests to the host. The host proxies server requests to the MCP server and handles UI requests directly. For handling incoming host events, see Event Handlers.

If you are deciding which method to use from an iframe View, start with the View API Guide. It compares callServerTool(), readServerResource(), updateModelContext(), sendMessage(), sampling, app-side tools, downloads, links, display modes, logs, and teardown.

callServerTool

Call a tool on the originating MCP server (proxied through the host).

async callServerTool(
  params: { name: string; arguments?: Record<string, unknown> },
  options?: RequestOptions,
): Promise<CallToolResult>

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.structuredContent);
}

Tool-level execution errors are returned in the result with isError: true rather than throwing exceptions. Transport or protocol failures throw. Always check result.isError.

sendMessage

Send a message to the host’s chat interface.

async sendMessage(
  params: { role: "user"; content: ContentBlock[] },
  options?: RequestOptions,
): Promise<{ isError?: boolean }>

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");
}

updateModelContext

Update the host’s model context with app state. Context is available to the model in future turns without triggering an immediate response. Each call overwrites any previous context.

async updateModelContext(
  params: {
    content?: ContentBlock[];
    structuredContent?: Record<string, unknown>;
  },
  options?: RequestOptions,
): Promise<void>

await app.updateModelContext({
  content: [{
    type: "text",
    text: `User is viewing page ${currentPage} of ${totalPages}`,
  }],
});

For large follow-up messages, offload data to updateModelContext first, then send a brief trigger via sendMessage:

await app.updateModelContext({
  content: [{ type: "text", text: fullTranscript }],
});
await app.sendMessage({
  role: "user",
  content: [{ type: "text", text: "Summarize the key points" }],
});

openLink

Request the host to open an external URL in the browser.

async openLink(
  params: { url: string },
  options?: RequestOptions,
): Promise<{ isError?: boolean }>

const { isError } = await app.openLink({
  url: "https://docs.example.com",
});
if (isError) {
  console.warn("Link request denied by host");
}

downloadFile

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.

async downloadFile(
  params: { contents: (EmbeddedResource | ResourceLink)[] },
  options?: RequestOptions,
): Promise<{ isError?: boolean }>

// Download embedded text content
await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///export.json",
      mimeType: "application/json",
      text: JSON.stringify(data, null, 2),
    },
  }],
});

// Download embedded binary content
await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///image.png",
      mimeType: "image/png",
      blob: base64EncodedPng,
    },
  }],
});

// Download via resource link (host fetches)
await app.downloadFile({
  contents: [{
    type: "resource_link",
    uri: "https://api.example.com/reports/q4.pdf",
    name: "Q4 Report",
    mimeType: "application/pdf",
  }],
});

readServerResource

Read a resource from the originating MCP server (proxied through the host).

async readServerResource(
  params: { uri: string },
  options?: RequestOptions,
): Promise<ReadResourceResult>

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 blob = new Blob([binary], { type: content.mimeType });
  videoElement.src = URL.createObjectURL(blob);
}

listServerResources

List available resources on the originating MCP server (proxied through the host). Supports pagination via cursor.

async listServerResources(
  params?: { cursor?: string },
  options?: RequestOptions,
): Promise<ListResourcesResult>

const result = await app.listServerResources();

for (const resource of result.resources) {
  console.log(resource.name, resource.uri, resource.mimeType);
}

// Paginate if more results exist
if (result.nextCursor) {
  const next = await app.listServerResources({ cursor: result.nextCursor });
}

requestDisplayMode

Request the host to change the display mode.

async requestDisplayMode(
  params: { mode: McpUiDisplayMode },
  options?: RequestOptions,
): Promise<{ mode: McpUiDisplayMode }>

The returned mode is the mode actually set — it may differ from the requested mode if unsupported.

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");
}

sendLog

Send log messages to the host for debugging. Logs are not added to the conversation.

sendLog(params: { level: string; data: string; logger?: string }): Promise<void>

app.sendLog({
  level: "info",
  data: "Weather data refreshed",
  logger: "WeatherApp",
});

requestTeardown

Request the host to tear down this app. The host may approve or ignore the request. If approved, the host will send the standard ui/resource-teardown request back to the app (triggering onteardown) before unmounting the iframe.

async requestTeardown(params?: {}): Promise<void>

// App-initiated close (e.g., "Done" button)
await app.requestTeardown();

createSamplingMessage

Request an LLM completion from the host via standard MCP sampling/createMessage. The host has full discretion over model selection and may modify or reject the request. Check app.getHostCapabilities()?.sampling before calling.

async createSamplingMessage(
  params: CreateMessageRequest["params"],
  options?: RequestOptions,
): Promise<CreateMessageResult | CreateMessageResultWithTools>

const result = await app.createSamplingMessage({
  messages: [
    { role: "user", content: { type: "text", text: "Summarize this." } },
  ],
  maxTokens: 100,
});
console.log(result.content);

When params.tools is provided, the result may contain tool_use blocks and stopReason: "toolUse". Check getHostCapabilities()?.sampling?.tools before passing tools.

registerTool

Register a tool that the host can call. Uses Standard Schema (Zod, ArkType, Valibot) for input/output validation. Returns a handle with enable(), disable(), remove(), and update() methods.

registerTool<OutputArgs, InputArgs>(
  name: string,
  config: {
    title?: string;
    description?: string;
    inputSchema?: InputArgs;
    outputSchema?: OutputArgs;
    annotations?: ToolAnnotations;
    _meta?: Record<string, unknown>;
  },
  cb: AppToolCallback<InputArgs, OutputArgs>,
): RegisteredAppTool

const handle = app.registerTool("get_selection", {
  description: "Get the user's current selection",
}, () => ({
  content: [{ type: "text", text: selectedText }],
}));

// Later: update, disable, or remove
handle.update({ description: "Updated description" });
handle.disable();
handle.remove();

sendToolListChanged

Notify the host that the app’s tool list has changed. Call this after registerTool, remove(), enable(), or disable().

async sendToolListChanged(params?: {}): Promise<void>

await app.sendToolListChanged();

sendSizeChanged

Manually notify the host of a UI size change. If autoResize is enabled (default), this is called automatically.

sendSizeChanged(params: { width?: number; height?: number }): Promise<void>

app.sendSizeChanged({ width: 400, height: 600 });

The sunpeak framework provides React convenience hooks that wrap these methods: useCallServerTool, useCreateSamplingMessage, useDownloadFile, useListServerResources, useReadServerResource, useRegisterTool, useSendMessage, useSendToolListChanged, useUpdateModelContext, useOpenLink, useRequestDisplayMode, useRequestTeardown, and useSendLog.

​Overview

​requestTeardown

​registerTool

​sendToolListChanged

Overview

requestTeardown

registerTool

sendToolListChanged