Skip to main content
All posts

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

Abe Wheeler
MCP AppsMCP App FrameworkMCP App TestingChatGPT AppsChatGPT App TestingClaude ConnectorsClaude Connector TestingView ToolsApp-Provided Tools
MCP App view tools let a rendered app expose a small, typed interface back to the model.

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_rows
  • set_date_range
  • reset_filters
  • get_current_view
  • move_cursor
  • read_visible_items
  • apply_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:

NeedPattern
UI needs backend workcallServerTool to a server tool
UI needs to tell the model what changeduseAppState or updateModelContext
Model needs to query or command the live UIView 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.

QuestionServer toolView tool
Where does it run?MCP serverApp iframe
How long does it live?As long as the server connectionAs long as the rendered app instance
Can it use secrets?Yes, if the server owns themNo, avoid secrets in browser code
Can it write to a database?YesUsually no
Can it read live UI state?Only if the UI sends itYes
Can it survive iframe teardown?YesNo
Best forAPIs, databases, auth, durable jobsSelection, 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 overdue filter.”
  • “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:

  1. View tool returns the current selection.
  2. Model explains the proposed write.
  3. User reviews and confirms the exact records in the app.
  4. App calls a server tool through callServerTool.
  5. 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 flowView tool pathFallback path
Model asks for current selectionget_selected_rowsPush selection through useAppState on each change
Model changes a filterset_filterAsk user to click a visible filter control or send a message
Model reads viewport boundsget_current_viewStore bounds with useAppState after pan or zoom
Model requests exportprepare_export_view_state, then server writeButton 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 content plus typed structuredContent.
  • 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
  • isError results 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/initialize handshake.
  • Check that the view advertised tools, then list the view’s tools through the bridge. Do not use the server’s tools/list for this assertion.
  • Call the read-only tool and assert structuredContent matches 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

Documentation →
npx sunpeak new

Further Reading

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.