Frontend tools and app context

Server MCP tools call backend systems. Frontend tools run inside your app as AG-UI frontend tools. Use frontend tools when the agent needs to interact with local UI state, page context, or host-app workflows that do not belong in the server runtime.

Embedded agents can combine app-local frontend tools with server-side MCP tools.

The transport boundary is deliberate:

• AgentSDK sends frontendTools to the agent as AG-UI frontend tool schemas.
• The agent can request a frontend tool and wait for the browser to return its result.
• MCP server tools are not executed in the browser; they still run through MCP Stack's server-side Gateway/AuthGateway path.

When to use frontend tools#

Use frontend tools for:

• Opening an app route.
• Reading selected row IDs from the current page.
• Drafting content into a text area.
• Applying filters to a local table.
• Triggering a UI workflow that already exists in the app.

Use server MCP tools for:

• Authoritative backend reads.
• Authoritative backend writes.
• Cross-session data.
• Operations that need downstream API auth.
• Actions that should appear in server/Gateway logs.

Example frontend tool#

<McpStackChat
  apiKey={apiKey}
  agentId={agentId}
  appSessionKey={session.id}
  userIdentity={userIdentity}
  appContext={{
    page: "ticket-detail",
    ticketId,
    selectedTab,
  }}
  frontendTools={{
    draft_internal_note: {
      description: "Draft an internal note in the current ticket editor without saving it.",
      parameters: {
        body: { type: "string", required: true },
      },
      execute: async ({ body }) => {
        setDraftNote(body);
        return { status: "drafted" };
      },
    },
  }}
/>

Safety rules#

Frontend tools are app code. Treat them like privileged UI actions:

• Use clear names and descriptions.
• Keep input schemas narrow.
• Avoid returning secrets, hidden form fields, or unnecessary page data.
• Require confirmation for destructive actions.
• Prefer draft/update UI actions over immediate irreversible writes.
• Keep authoritative writes on backend MCP tools when auditability matters.

App context#

Use appContext for facts that help the agent understand the current screen.

Good context:

appContext={{
  page: "account-detail",
  accountId: "acct_123",
  visibleTicketIds: ["T-100", "T-101"],
  selectedTab: "activity",
}}

Avoid sending:

• Full page HTML.
• Access tokens.
• Large hidden datasets.
• Secrets or private fields unrelated to the task.

Quick answer#

To let the agent "control the app," decide whether each action is local UI state or an authoritative backend operation. Use frontendTools for local UI behavior and server MCP tools for backend reads and writes.