AG-UI agent transport

MCP Stack Agents speak AG-UI at the frontend boundary. That lets AgentSDK, CopilotKit, or a custom AG-UI client connect to the same agent without changing how servers, Gateway, or AuthGateway work.

For the customer-facing overview, see AG-UI agents for SaaS apps. For the dogfood dashboard surface, see In-app agent operations.

AgentSDK / CopilotKit / custom AG-UI frontend
        -> AG-UI
MCP Stack Agent
        -> MCP
MCP Stack Server
        -> Gateway / AuthGateway
        -> SaaS API

Endpoint#

AG-UI clients run an agent through:

POST /api/v1/agents/{agentId}/ag-ui
Accept: text/event-stream
Authorization: Bearer mcpstack_pk_...

The response is a data-only Server-Sent Events stream. Each data: payload is an AG-UI event object with a type.

What streams#

The agent stream includes:

• assistant message start, deltas, and end events
• tool call start, argument, end, and result events
• frontend tool requests for frontendTools
• runtime snapshots such as budget state
• errors
• run completion

Frontend tools#

frontendTools are AG-UI frontend tools. They are right for local app behavior:

• navigate to a route
• read selected table rows
• draft into an editor
• apply a local filter
• ask the user for input
• render a host-app table, chart, or approval card

Frontend tools should not perform authoritative backend writes directly. If a durable write matters for audit, permissions, or consistency, expose it as a server MCP tool.

Server MCP tools#

Server tools still run through MCP Stack's server-side path.

For app-token embeds, AgentSDK forwards the current host-app token with the AG-UI run. When the agent needs a server MCP tool, MCP Stack exchanges that host token through Gateway, starts an MCP session, calls the tool, records the result, and continues the agent run.

That means AG-UI does not bypass:

• Gateway token validation
• AuthGateway policy
• MCP server authorization
• agent budgets
• request and tool-call logs
• organization and resource permissions

AgentSDK behavior#

AgentSDK is the first-party integration point:

import { useAppAgent } from "@mcpstack/agent-sdk/react";
 
const agent = useAppAgent({
  apiKey: "mcpstack_pk_...",
  agentId: "ag_support",
  appSessionKey: session.id,
  userIdentity: {
    subject: user.id,
    email: user.email,
    organizationId,
  },
  auth: {
    mode: "app-token",
    getToken: () => session.getAccessToken(),
  },
  appContext: {
    page: "ticket-detail",
    ticketId,
  },
  frontendTools,
});

AgentSDK uses AG-UI for agent turns. The public app model is useAppAgent, createAppAgent, and McpStackChat, with frontendTools for app-local actions.

Custom clients#

A custom AG-UI client should send:

• threadId for conversation continuity
• runId for the current run
• messages with the latest user message or tool result
• tools for frontend tool schemas
• context or forwardedProps.mcpstack.context for app context
• forwardedProps.mcpstack.externalUserId or externalUser for budget and identity attribution

Use frontendTools or AG-UI frontend tools for app-local behavior. Use MCP servers for authoritative backend capabilities.

Quick answer#

AG-UI is the frontend protocol for MCP Stack Agents. MCP remains the server tool protocol, and Gateway/AuthGateway remain the control layer for backend access.

In the MCP Stack dashboard, the embedded MCP Stack Operator uses this same AgentSDK AG-UI path. Its browser tools provide page context, navigation, approval cards, and rendering; its server tools still run through the seeded MCP Stack Operations MCP server.