> ## 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.

# Cloudflare Agents

> Add Kontext integrations to Cloudflare Agents with the withKontext mixin.

The `withKontext` mixin adds Kontext capabilities to any Cloudflare Agent. It handles MCP OAuth, credential storage via Durable Objects, and exposes your integrations as ready-to-use tools.

## Install

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

## Complete example

```typescript theme={"system"}
import { Agent } from "agents";
import { withKontext } from "@kontext-dev/js-sdk/cloudflare";

class MyAgent extends withKontext(Agent) {
  async onChatMessage(onFinish) {
    const tools = await this.kontextTools();
    const systemPrompt = this.kontextSystemPrompt;
    // Use tools with your LLM of choice
  }
}

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return MyAgent.mount("/agent").fetch(request, env, ctx);
  },
};
```

## What `withKontext` adds

`withKontext(AgentClass)` is a mixin that extends your Agent class with Kontext capabilities. It hooks into the Agent lifecycle automatically:

* **`onConnect`** -- Captures the callback host used for OAuth popup redirects.
* **`onStart`** -- Configures the OAuth callback response handler.
* **`onRequest`** -- Delegates MCP transport and OAuth callback requests to the built-in MCP handler.

The mixin adds three members to your agent:

* **`this.kontextTools()`** -- Returns a `Promise<ToolSet>` with all tools from connected integrations. Call this in message handlers (e.g. `onChatMessage`) after `onConnect` has fired. On first run, `onConnect` must set the callback host before `kontextTools()` can connect to Kontext.
* **`this.kontextSystemPrompt`** -- A string describing which integrations are connected and available. Pass it to your LLM as the system prompt.
* **`this.createMcpOAuthProvider(callbackUrl)`** -- Returns a `KontextCloudflareOAuthProvider` instance. The `callbackUrl` parameter is required. Override this method to customize the OAuth provider.

## OAuth with Durable Object storage

`KontextCloudflareOAuthProvider` stores OAuth tokens and session state in Durable Objects. The mixin configures this automatically using your `KONTEXT_CLIENT_ID` environment variable.

```typescript theme={"system"}
import {
  withKontext,
  KontextCloudflareOAuthProvider,
} from "@kontext-dev/js-sdk/cloudflare";
```

If you need to customize the OAuth provider (for example, to use a different storage backend), override `createMcpOAuthProvider()` in your agent class:

```typescript theme={"system"}
class MyAgent extends withKontext(Agent) {
  createMcpOAuthProvider(callbackUrl: string) {
    return new KontextCloudflareOAuthProvider({
      kontextClientId: this.env.KONTEXT_CLIENT_ID,
      storage: this.ctx.storage,
      agentName: this.name,
      callbackUrl,
    });
  }
}
```

## Wrangler configuration

Add `KONTEXT_CLIENT_ID` to your `wrangler.toml`:

```toml theme={"system"}
[vars]
KONTEXT_CLIENT_ID = "app_your-app-id"
```

For production, use secrets instead of plaintext vars:

```bash theme={"system"}
npx wrangler secret put KONTEXT_CLIENT_ID
```

## Environment bindings

Your `Env` type needs to include the Kontext client ID and any Durable Object bindings the SDK uses:

```typescript theme={"system"}
interface Env {
  KONTEXT_CLIENT_ID: string;
  AI: Ai;
  // Your other bindings
}
```

The `withKontext` mixin reads `KONTEXT_CLIENT_ID` from the environment automatically. No additional configuration is needed beyond setting the variable.

Optionally set `KONTEXT_SERVER_URL` to point at a non-default Kontext API host.

## Using tools with an LLM

Once you have tools from `kontextTools()`, pass them to any LLM SDK:

```typescript theme={"system"}
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

class MyAgent extends withKontext(Agent) {
  async onChatMessage(onFinish) {
    const tools = await this.kontextTools();
    const systemPrompt = this.kontextSystemPrompt;

    const result = await generateText({
      model: openai("gpt-4o"),
      tools,
      system: systemPrompt,
      prompt: "List my recent GitHub notifications",
      maxSteps: 5,
    });

    // Send result back to the client
    this.send(result.text);
  }
}
```

## Next steps

* [React SDK](/frameworks/react) -- Build a frontend that connects to your Cloudflare Agent.
* [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.