Skip to main content
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

npm install @kontext-dev/js-sdk react agents

​
Complete example

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. 
<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). 
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: 
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: 
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: 
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