MCP App View Tools: App-Provided Tools That Run in the Browser (October 2026)

MCP App view tools let a rendered app expose a small, typed interface back to the model.
An MCP App view tool lets a host ask the open app for live state or request a local UI action. The MCP Apps draft calls these app-provided tools. They run in the rendered iframe, so a tool such as invoice_review_get_selection can return the rows the user has selected right now.
TL;DR: A view advertises a tools capability, registers a typed handler, and answers the host’s tools/list and tools/call requests through the iframe bridge. Use this for current UI state and local commands. Keep privileged or durable work on the MCP server, and test a fallback because app-provided tools are still in the draft specification.
What View Tools Are
In normal MCP, tools live on the server. The host asks the MCP server for tools/list, the model chooses a tool, and the host calls the server with tools/call.
The draft adds a second direction. A rendered app can expose its own tools while the iframe is loaded. A supporting host lists those tools through the iframe bridge and can call them through standard MCP tool messages. These tools are separate from the server’s tools/list catalog.
That gives the model a typed interface to the current view.
Without view tools, the app is mostly opaque to the model. The model may know what the server returned and may receive pushed state through updateModelContext or useAppState, but it cannot query the live selection or viewport on demand through a standard view-tool call.
With view tools, the app can expose small commands:
get_selected_rowsset_date_rangereset_filtersget_current_viewmove_cursorread_visible_itemsapply_local_sort
Those tools run in the app iframe, against the state the user is actually seeing.
Follow the Two Tool Directions
The names are easy to confuse because both directions use tools/call. In the draft protocol, the route determines which tool runs:
Model or host -> View: tools/list -> tools/call -> browser handler
View -> host -> MCP server: tools/call -> server handler
The view declares tools in its ui/initialize request. Once initialization completes, the host can ask the view for its tool list and invoke a handler. The host’s serverTools capability is a separate signal that allows the view to call server tools. Neither signal alone guarantees the host will expose view tools to its model, so test the actual host behavior.
You can think about the three paths this way:
| Need | Pattern |
|---|---|
| UI needs backend work | callServerTool to a server tool |
| UI needs to tell the model what changed | useAppState or updateModelContext |
| Model needs to query or command the live UI | View tool or app-provided tool |
An app may use all three. For example, a user selects invoices in the view, useAppState records the committed IDs, a view tool answers a model request for the current visible selection, and a server tool performs a confirmed write.
Server Tools vs View Tools
The most important design choice is where the tool should live.
| Question | Server tool | View tool |
|---|---|---|
| Where does it run? | MCP server | App iframe |
| How long does it live? | As long as the server connection | As long as the rendered app instance |
| Can it use secrets? | Yes, if the server owns them | No, avoid secrets in browser code |
| Can it write to a database? | Yes | Usually no |
| Can it read live UI state? | Only if the UI sends it | Yes |
| Can it survive iframe teardown? | Yes | No |
| Best for | APIs, databases, auth, durable jobs | Selection, viewport, local state, UI commands |
If the action needs a token, database, file system, billing API, or audit log, keep it on the server.
If the action is about the current view, such as “what item is selected?” or “zoom the chart to this range,” a view tool is a good fit.
A Simple View Tool Shape
The MCP Apps SDK App class can register tools from the view side. Declare the tools capability before connecting, then give each tool a name, an input schema, and a result. The SDK validates the schemas you provide.
import { App } from '@modelcontextprotocol/ext-apps';
import { z } from 'zod';
const app = new App(
{ name: 'InvoiceReview', version: '1.0.0' },
{ tools: { listChanged: true } }
);
// Keep this value in sync with the visible table selection.
let selectedInvoiceIds: string[] = [];
app.registerTool(
'invoice_review_get_selection',
{
description: 'Return the invoice rows currently selected in the visible review table.',
inputSchema: z.object({}),
outputSchema: z.object({
selectedIds: z.array(z.string()),
count: z.number(),
}),
annotations: {
readOnlyHint: true,
},
},
async () => {
return {
content: [
{
type: 'text',
text: `${selectedInvoiceIds.length} invoices are selected.`,
},
],
structuredContent: {
selectedIds: selectedInvoiceIds,
count: selectedInvoiceIds.length,
},
};
}
);
The model does not scrape the DOM. A supporting host calls invoice_review_get_selection and gets a typed result. The app must update selectedInvoiceIds when its visible selection changes; returning stale state would make the tool misleading.
That distinction matters. DOM scraping couples the model to pixels and markup. A view tool gives the model a semantic contract that your app owns.
A Command Tool Example
Read-only state tools are the safest place to start. Command tools need more care because they change what the user sees.
app.registerTool(
'invoice_review_set_filter',
{
description: 'Set the visible invoice status filter in the current invoice review view.',
inputSchema: z.object({
status: z.enum(['all', 'open', 'paid', 'overdue']),
}),
outputSchema: z.object({
status: z.enum(['all', 'open', 'paid', 'overdue']),
visibleCount: z.number(),
}),
annotations: {
readOnlyHint: false,
},
},
async ({ status }) => {
setInvoiceFilter(status);
const visibleCount = countVisibleInvoices();
return {
content: [{ type: 'text', text: `Filter set to ${status}.` }],
structuredContent: { status, visibleCount },
};
}
);
This tool changes the local filter, so it must not claim readOnlyHint: true. The annotation is a hint for the host, not proof of approval. Register both tools before app.connect() so the host can discover them when the view initializes.
For a destructive action, let the view collect confirmation, then call a server tool that checks authorization, validates the request, and records the write. A browser handler cannot be the final authority for an account or database change.
Keep the Tool List in Sync With the View
A view tool exists only while its iframe exists. If the current screen no longer has a selection, a get_selection tool may still be useful because it can return an empty array. A tool that depends on a closed panel may need to disappear from tools/list entirely.
The SDK’s registered tool handle supports disable(), enable(), update(), and remove(). When the app declares listChanged: true, those changes notify the host so it can ask for the current list again. A host may still cache or display tools differently, so verify the removal behavior in the host you ship to. Do not assume disabling a tool cancels a call that is already running.
Keep names stable while a view is open, and scope them to the app or view. invoice_review_get_selection tells the model more than get_selection when several apps can appear in one conversation.
When to Use useAppState Instead
Use useAppState when the user changes something and the model should know later.
import { useAppState } from 'sunpeak';
function InvoiceSelection() {
const [state, setState] = useAppState({
selectedInvoiceIds: [] as string[],
statusFilter: 'all',
});
return (
<button onClick={() => setState({
...state,
selectedInvoiceIds: ['inv-42'],
})}>
Select invoice
</button>
);
}
That is a push model. The app updates model context after a user action, and the host can pass the latest update to the model on a later turn. Keep the payload small and send committed choices rather than every keystroke.
View tools are a pull model. The model asks for state or asks the app to do something.
Use useAppState for committed user choices:
- selected records
- approved steps
- submitted form values that the model needs
- active workflow state
Use view tools for live questions or commands:
- “Which rows are visible right now?”
- “Move to the next result.”
- “Return the current viewport bounds.”
- “Apply the
overduefilter.” - “Reset this temporary chart state.”
When the state matters after the current view tool call, sync it with useAppState after the command changes the UI. The sunpeak useAppState guide shows the state path in more detail.
When to Use callServerTool Instead
Use callServerTool when a UI action needs server-side work.
Examples:
- load the next page from an API
- save a draft
- validate a form against backend rules
- start an export job
- write to a database
- refresh data with user credentials
The view can still provide a small tool that lets the model ask for the current UI state, but the actual write should cross back to the server.
import { useCallServerTool } from 'sunpeak';
function SaveSelectionButton({ selectedIds }: { selectedIds: string[] }) {
const callServerTool = useCallServerTool();
async function saveSelectedInvoices() {
return callServerTool({
name: 'save_invoice_selection',
arguments: { selectedIds },
});
}
return <button onClick={saveSelectedInvoices}>Save selection</button>;
}
A practical pattern for a confirmed write is:
- View tool returns the current selection.
- Model explains the proposed write.
- User reviews and confirms the exact records in the app.
- App calls a server tool through
callServerTool. - Server performs the durable write.
That keeps the view useful without moving trusted work into browser JavaScript.
Capability Detection and Fallbacks
Do not assume every host exposes app-provided tools to its model. The versioned MCP Apps specification does not define them; the draft does. The SDK can register them, but basic MCP App rendering does not prove that a particular host will list or call them.
A portable app should work through visible controls, useAppState, and server tools when the host does not route view tools. Test this in each target host and client version. The app’s own tools capability advertises what it provides; it is not a host-support flag.
Fallback examples:
| Desired flow | View tool path | Fallback path |
|---|---|---|
| Model asks for current selection | get_selected_rows | Push selection through useAppState on each change |
| Model changes a filter | set_filter | Ask user to click a visible filter control or send a message |
| Model reads viewport bounds | get_current_view | Store bounds with useAppState after pan or zoom |
| Model requests export | prepare_export_view_state, then server write | Button calls an app-only server tool |
Fallbacks matter because support can differ by release, platform, or security policy. Keep the workflow usable even when the host ignores the view’s tool catalog.
Security Rules for View Tools
View tools run inside a sandboxed iframe. Treat them as untrusted app code from the host’s point of view, and as browser code from your point of view.
Follow these rules:
- Give every view tool a namespaced name, such as
invoice_review_get_selection. - Keep schemas narrow. Avoid arbitrary JSON blobs unless there is no better shape.
- Mark read-only tools with
readOnlyHint: true. - Mark tools with side effects as not read-only, and require explicit confirmation for durable or destructive work.
- Return small, model-readable
contentplus typedstructuredContent. - Never put tokens, secrets, or private implementation data in tool results.
- Keep handlers short and bound calls with timeouts; move work that may outlive the iframe to the server.
- Disable or unregister tools when the relevant UI state is gone.
- Keep writes on the server unless the action is purely local UI state.
Namespacing deserves extra attention. A generic name like search is ambiguous when several apps or server tools appear in one conversation. map_view_search_visible_markers tells the host what state the call will inspect.
Lifecycle Rules
View tools are tied to the current app instance.
That means:
- They become available only after the app initializes and advertises its tools capability.
- They can change while the app is open.
- The app should notify the host when the tool list changes.
- They disappear when the iframe is torn down.
- Calls after teardown must fail rather than silently using stale view state.
This is why view tools are a poor fit for long-running work. If the task needs to continue after the user scrolls away, reloads, closes the chat, or the host reclaims the iframe, the task belongs on the server.
How to Test View Tools
Test view tools like a protocol contract, not just a React event.
Start with unit tests for the handler:
- valid input returns the expected
structuredContent - invalid input fails before changing state
- read-only tools do not mutate state
- command tools update the intended state only
isErrorresults are handled by the caller
Then add a browser test against a local host bridge. The SDK AppBridge API gives a host getAppCapabilities(), listTools(), and callTool() for the view after initialization. Test this sequence:
- Render the view and wait for its
ui/initializehandshake. - Check that the view advertised
tools, then list the view’s tools through the bridge. Do not use the server’stools/listfor this assertion. - Call the read-only tool and assert
structuredContentmatches the current visible selection. - Call a local command, assert the UI changed, and check any model-context update that should follow.
- Send invalid arguments and confirm the handler did not change state.
- Disable a conditional tool, wait for
notifications/tools/list_changed, and list again. - Tear down the iframe and confirm a later call fails instead of using old state.
For cross-host testing, include a run with view tools unavailable. The app should still be usable through visible controls. Test server writes separately with real authorization checks; a mocked browser call does not prove the backend is safe.
sunpeak’s inspector and testing framework can pin view state and cover the visible fallback before a live-host check. Its useAppTools hook registers view-provided tools from a React resource; useCallServerTool is the opposite direction. Keep the host-bridge test for discovery and invocation because a view rendering test alone cannot prove that the model can call its tools.
A Practical Checklist
Before you add a view tool, answer these questions:
- Does the model need to pull this state, or can the app push it with
useAppState? - Does this action need secrets, durable storage, or an external API?
- What happens if the iframe is destroyed halfway through?
- Is the tool name scoped to the app and current view?
- Is the schema tight enough to validate before the handler runs?
- What user confirmation is required before any durable or destructive effect?
- What is the fallback when the host does not support view tools?
- Can this be tested locally without a real host account?
If the answer points to live UI state, a view tool is a good fit. If the answer points to durable work, use a server tool.
What to Build First
Start with one read-only view tool. Do not begin with a write action.
A good first tool is get_current_selection, get_visible_items, or get_view_state. It teaches the host and model what the app can expose without changing user data. Once that works, add one command tool with a narrow schema and a clear fallback.
The view owns live interaction, the server owns durable work, and a supporting host can give the model typed tools for state it cannot read from pixels.
When you are ready to test that boundary, run the app in sunpeak, exercise the bridge locally, and add a cross-host fallback test. The first time a host changes tool support, you want a failing test, not a production bug.
Get Started
npx sunpeak newFurther Reading
- MCP App actions - callServerTool, sendMessage, and updateModelContext
- Interactive MCP Apps with useAppState - two-way UI state patterns
- MCP App lifecycle - connect, tool input, results, and teardown
- MCP App tool metadata - resourceUri, visibility, and app-only tools
- Testing MCP App data flow - content, structuredContent, _meta, and host bridge state
- Cross-host compatibility testing for MCP Apps
- MCP App capability detection - host features and fallbacks
- MCP App state persistence - app state and server storage
- MCP App framework
- MCP App testing framework
- sunpeak docs - MCP Apps introduction
- Official MCP Apps overview
- MCP Apps draft - app-provided tools
- MCP Apps SDK - App.registerTool API
- MCP Apps SDK - host AppBridge API
Frequently Asked Questions
What are MCP App view tools?
View tools, called app-provided tools in the MCP Apps draft, are registered by the rendered iframe rather than the MCP server. A supporting host can list and call them over the iframe bridge while that view is open. They are useful for reading a current selection or changing a local filter, but support must be verified in each target host.
What is the difference between a view tool and a server tool?
A server tool lives on the MCP server and is available whenever the server is connected. A view tool lives inside the app iframe, runs in browser JavaScript, and disappears when the iframe is torn down. Use server tools for durable work, privileged API calls, database writes, and long-running jobs. Use view tools for live UI state, local interactions, and semantic commands against the current app instance.
Should I use useAppState or a view tool?
Use useAppState when a committed user choice should be available to the model on a later turn. Use a view tool when a supporting host needs to ask the open view for its current state or invoke a local command. For important choices, update model context after the view tool changes the UI so the model can use the choice later.
Do view tools replace callServerTool?
No. callServerTool sends work from the app back to the MCP server through the host bridge. View tools go the other direction: the host calls a tool implemented inside the app view. If the work needs secrets, durable storage, external APIs, or a job that outlives the iframe, keep it on the server and call it with callServerTool.
Are view tools safe?
Treat view tools as browser code. Validate arguments and output, keep secrets on the server, and use short timeouts. readOnlyHint is an advisory annotation, not an approval mechanism. A destructive or durable action needs server-side authorization and a real user confirmation path even if a view tool starts the flow.
How do I test MCP App view tools?
Render the view in a host bridge test, wait for initialization, then list its tools and call each handler through the bridge. Check input validation, structuredContent, UI changes, list-changed behavior, and teardown. Also test a host that never exposes view tools, because the feature remains in the MCP Apps draft and host support varies.
Can ChatGPT Apps and Claude Connectors use view tools?
The MCP Apps SDK exposes app-provided tools, but a target host must also surface and route them to the model. Do not infer support from basic MCP App rendering. Check the target host in the version and environment you deploy to, and keep a visible control or useAppState fallback when the tool is unavailable.