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.
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.
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");
}
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" }],
});
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");
}
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",
}],
});
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);
}
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 });
}
async requestDisplayMode(
params: { mode: McpUiDisplayMode },
options?: RequestOptions,
): Promise<{ mode: McpUiDisplayMode }>
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(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();
autoResize is enabled (default), this is called automatically.
sendSizeChanged(params: { width?: number; height?: number }): Promise<void>
app.sendSizeChanged({ width: 400, height: 600 });
