> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.security/llms.txt
> Use this file to discover all available pages before exploring further.

# React

> Add Kontext authentication and integration management to React applications.

The React SDK provides a provider and hooks that handle OAuth via popup windows. Your users authenticate and connect integrations without leaving your app.

## Install

```bash theme={"system"}
npm install @kontext-dev/js-sdk react agents
```

## Complete example

```tsx theme={"system"}
import { KontextProvider } from "@kontext-dev/js-sdk/react";
import {
  useKontextAgent,
  useKontextContext,
} from "@kontext-dev/js-sdk/react/cloudflare";

function App() {
  return (
    <KontextProvider>
      <ChatInterface />
    </KontextProvider>
  );
}

function ChatInterface() {
  const { authenticating } = useKontextContext();
  const agent = useKontextAgent({ agent: "my-agent" });

  if (authenticating) return <div>Signing in...</div>;

  return <div>Chat UI here</div>;
}
```

## `KontextProvider`

Wrap your app with `KontextProvider` to manage the OAuth popup lifecycle. The provider internally uses the `useKontext` hook and passes its state to all child components via React Context.

```tsx theme={"system"}
<KontextProvider popupFeatures="width=500,height=700">
  {children}
</KontextProvider>
```

Props:

* **`popupFeatures`** -- A string passed to `window.open()` to control popup size and position. Defaults to `"width=600,height=700"`.
* **`onAuthComplete`** -- Called when the auth popup closes.

The provider opens a popup for the OAuth flow automatically when the MCP server requires authentication. No redirect handling or callback routes are needed in your app.

## `useKontext` hook

The low-level hook for popup handling. Use it directly when you want to wire MCP updates yourself (for example with `useAgent` from `agents/react`).

```tsx theme={"system"}
const { authenticating, onMcpUpdate, handleElicitationUrl } = useKontext();
const agent = useAgent({ agent: "my-agent", onMcpUpdate });
```

Returns:

* **`authenticating`** -- `true` while the OAuth popup is open and the user is signing in. Use this to show a loading state.
* **`onMcpUpdate`** -- A callback function that receives MCP state updates. Pass this to your agent framework to keep tool state in sync.
* **`handleElicitationUrl`** -- A function that opens a popup for integration-specific OAuth. Call this when a user needs to connect a new integration (GitHub, Slack, etc.).

## OAuth popup flow

The SDK handles OAuth entirely through popups:

1. `KontextProvider` detects the user needs to authenticate.
2. A popup opens to the Kontext authorization page.
3. The user signs in and grants consent.
4. The popup redirects to the backend's OAuth callback handler, the authorization code is exchanged for tokens, and the popup closes.
5. `authenticating` flips to `false` and your app has a valid session.

No route handlers or callback pages are needed in your frontend. The backend handles the OAuth callback; the React SDK detects when the popup closes and resumes the session.

## Integration with Cloudflare `useAgent`

Pass `onMcpUpdate` to the `useAgent` hook to sync MCP tool state between your Cloudflare Agent and the React frontend:

```tsx theme={"system"}
import { useAgent } from "agents/react";
import { useKontext } from "@kontext-dev/js-sdk/react";

function ChatInterface() {
  const { onMcpUpdate, handleElicitationUrl } = useKontext();
  const agent = useAgent({ agent: "my-agent", onMcpUpdate });

  return <div>{/* Render chat using agent state */}</div>;
}
```

When the agent's MCP state changes (tools added, integrations connected or disconnected), `onMcpUpdate` keeps the frontend in sync.

If you're already using `KontextProvider`, you can skip this manual wiring and use `useKontextAgent()` from `@kontext-dev/js-sdk/react/cloudflare`.

## Integration connection popups

When a user needs to connect an integration they haven't authorized yet, call `handleElicitationUrl` with the connection URL:

```tsx theme={"system"}
function ConnectButton({ url }: { url: string }) {
  const { handleElicitationUrl } = useKontext();

  return (
    <button onClick={() => handleElicitationUrl(url)}>
      Connect Integration
    </button>
  );
}
```

This opens a popup for the integration's OAuth flow, the same pattern as the initial Kontext sign-in. The popup closes when the connection completes.

## `useKontextContext`

Access the raw provider state if you need lower-level control:

```tsx theme={"system"}
import { useKontextContext } from "@kontext-dev/js-sdk/react";

const context = useKontextContext();
```

This returns the full internal state of the `KontextProvider`. If you're integrating with Cloudflare Agents, prefer `useKontextAgent` for most cases.

## Next steps

* [Cloudflare Agents](/frameworks/cloudflare) -- Build the backend agent that pairs with your React frontend.
* [Vercel AI SDK](/frameworks/vercel-ai) -- Use Kontext tools with `generateText` and `streamText`.
* [How Kontext Works](/concepts/how-kontext-works) -- Understand the Kontext architecture and credential flow.