Client tools and app context

Server MCP tools call backend systems. Client tools run inside your app. Use client 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 client tools with server-side MCP tools.

When to use client tools#

Use client 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 client tool#

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

Safety rules#

Client 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 clientTools for local UI behavior and server MCP tools for backend reads and writes.