---
title: Auth-Gated UI
description: Gate GGUI renders behind your app's auth with a bearer token on useMcpAppsChat — and understand why OAuth tool-consent is the client's job, not GGUI's.
---

GGUI is a renderer, not an identity provider. Your app already knows who the user is. There are **two separate auth concerns**, and only the first is yours to wire:

1. **Authenticating your app → agent backend.** Every request `useMcpAppsChat` makes (prompt POST, snapshot GET, the iframe → MCP tool-call relay) carries a bearer token your app supplies. The backend gates chat ownership on the principal that token identifies. **This is the recipe below.**
2. **OAuth consent for tools the _agent_ calls.** When a tool the agent calls needs the end-user to authorize a third-party service (Google, Slack), that consent flow is **not** GGUI's responsibility — it belongs to MCP's OAuth standard, the hosting agent, and your client app. GGUI only surfaces an optional signal. See [OAuth tool-consent is the client's job](#oauth-tool-consent-is-the-clients-job).

## Gate the chat behind a bearer token

`useMcpAppsChat` takes two auth hooks:

- **`getAuthToken()`** — called before every request; return the bearer token to send as `Authorization: Bearer <token>` (or `undefined` for none).
- **`onUnauthenticated()`** — called on a `401`; refresh/re-mint your token, return `true` to retry the request once, `false` to surface the error.

The [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample uses these for a **guest-token** flow: it mints an anonymous token from the backend's `POST /auth/guest` mount, caches it, and re-mints on `401`. Swap that mint for your own user-session token and the same wiring gates renders behind a signed-in user:

```tsx
import { useCallback, useRef } from "react";
import { useMcpAppsChat } from "@ggui-ai/mcp-apps-react/chat-helpers";

function Chat({ agentEndpoint }: { agentEndpoint: string }) {
  const { user, getAccessToken, refreshSession } = useAuth(); // your auth provider

  // Read the current token per-request (kept in a ref so the callback
  // always sees the latest after a refresh).
  const tokenRef = useRef<string | undefined>(getAccessToken());
  const getAuthToken = useCallback(() => tokenRef.current, []);

  // 401 → refresh once, then retry. Return false to give up.
  const onUnauthenticated = useCallback(async () => {
    const fresh = await refreshSession();
    if (!fresh) return false;
    tokenRef.current = fresh;
    return true;
  }, [refreshSession]);

  const { entries, sessions, send, handleAppMessage } = useMcpAppsChat({
    chatEndpoint: `${agentEndpoint}/agent`,
    snapshotEndpoint: `${agentEndpoint}/agent`,
    getAuthToken,
    onUnauthenticated,
  });

  // render `entries` + mount `sessions` with <AppRenderer> as usual
}
```

The token rides every hook request automatically. The backend authenticates it and scopes the conversation (its `chatId` snapshot + resume state) to that principal — clear the session and you're a different principal with different chats.

### Mount-time gate

Don't open the chat until your provider says the user is signed in — a plain conditional render, exactly how the sample guards on `guestTokenReady`:

```tsx
function App({ agentEndpoint }: { agentEndpoint: string }) {
  const { isAuthenticated, isLoading } = useAuth();
  if (isLoading) return <p>Loading…</p>;
  if (!isAuthenticated) return <LoginPage />;
  return <Chat agentEndpoint={agentEndpoint} />;
}
```

### The tool-call relay carries the token too

When the iframe dispatches a tool call, your host relays it to the agent backend's `POST /agent` (`kind: "tool-call"`) inside `<AppRenderer onCallTool>`. Send the **same** bearer token on that relay so the MCP call runs as the signed-in user — the sample's `onCallTool` reads `getAuthToken()` and sets `Authorization: Bearer <token>` on the relay fetch. Don't trust anything the iframe puts in the payload as identity; the token on the relay is the credential.

## OAuth tool-consent is the client's job

A different situation: the agent wants to call a tool that needs the **end-user** to authorize a third-party service first (read their Google Calendar, post to Slack). That consent flow is deliberately **outside** the GGUI protocol. It is owned by:

- **MCP's OAuth standard** — the spec defines how an MCP server advertises that a tool needs authorization and how the consent/token exchange happens.
- **The hosting agent** (e.g. `@anthropic-ai/claude-agent-sdk`) — follows that spec to handle tool authorization.
- **Your end-user client app** — the surface actually talking to the agent backend pops its own consent UI and drives the redirect. Consent is a client decision, not something GGUI's runtime or protocol renders.
- **guuey's MCP proxy** — captures an OAuth credential once so multiple agents can reuse it (coming soon — part of the guuey platform, not the open GGUI protocol).

So GGUI itself renders no consent screen, and its wire carries no signal that one is needed — there is no frame, tool, or observability event through which a consent challenge travels. That is deliberate: the party that invokes the tool is the party that owns the user relationship and the chrome a prompt would render into, so the ceremony lives entirely in your host. See [Error Handling → renderer-side faults](/cookbook/error-handling/#renderer-side-faults-stay-inside-the-iframe) for what the observability channel _does_ carry.

## See also

- [React host helpers](/host-helpers/react/) — `useMcpAppsChat` (`getAuthToken` / `onUnauthenticated`) + `<AppRenderer>`
- [`ggui-basic-web` sample](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) — the runnable guest-token reference (`Chat.tsx`)
- [Error Handling](/cookbook/error-handling/) — HTTP `401` and the JSON-RPC auth codes
- [Build an agent on hosted GGUI](/quickstart/hosted-agent/) — the agent-side handshake → render → consume loop