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

# Client Types

> Type reference for createKontextClient, the client interface, tools, integrations, and storage.

## createKontextClient

```typescript theme={"system"}
import { createKontextClient } from "@kontext-dev/js-sdk/client";

const client = createKontextClient({
  clientId: "app_your-app-id",
  redirectUri: "http://localhost:3000/callback",
  onAuthRequired: (url) => { window.location.href = url.toString(); },
});

await client.connect();
const tools = await client.tools.list();
```

Creates a `KontextClient` instance. See [Client SDK](/client/overview) for the full usage guide.

## KontextClientConfig

Configuration passed to `createKontextClient`.

```typescript theme={"system"}
interface KontextClientConfig {
  clientId: string;
  redirectUri: string;
  url?: string;
  serverUrl?: string;
  storage?: KontextStorage;
  sessionKey?: string;
  onAuthRequired: (url: URL) => string | URL | void | Promise<string | URL | void>;
  onIntegrationRequired?: (url: string, info: { id: string; name?: string }) => void | Promise<void>;
  onStateChange?: (state: ClientState) => void;
}
```

| Option                  | Type                  | Description                                                                      |
| ----------------------- | --------------------- | -------------------------------------------------------------------------------- |
| `clientId`              | `string`              | Your application's OAuth client ID.                                              |
| `redirectUri`           | `string`              | Where to redirect after OAuth. Must match your application's registered URI.     |
| `url`                   | `string?`             | MCP server endpoint for single-endpoint mode. Omit for hybrid/orchestrated mode. |
| `serverUrl`             | `string?`             | Kontext API base URL. Defaults to `https://api.kontext.security`.                |
| `storage`               | `KontextStorage?`     | Token persistence backend. Defaults to `MemoryStorage`.                          |
| `sessionKey`            | `string?`             | Namespace prefix for storage keys. Use for multi-user isolation.                 |
| `onAuthRequired`        | `(url: URL) => ...`   | Called when the user needs to authenticate. Open or redirect to the URL.         |
| `onIntegrationRequired` | `(url, info) => void` | Called when an integration needs connecting. Show the connect URL to the user.   |
| `onStateChange`         | `(state) => void`     | Called on every state transition.                                                |

## KontextClient

The client instance returned by `createKontextClient`.

```typescript theme={"system"}
interface KontextClient {
  readonly state: ClientState;

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  getConnectPageUrl(): Promise<ConnectSessionResult>;

  readonly auth: {
    signIn(): Promise<void>;
    signOut(): Promise<void>;
    handleCallback(url: string | URL): Promise<void>;
    isCallback(url: string | URL): boolean;
    readonly isAuthenticated: boolean;
  };

  readonly integrations: {
    list(): Promise<IntegrationInfo[]>;
  };

  readonly tools: {
    list(options?: { limit?: number }): Promise<KontextTool[]>;
    execute(toolId: string, args?: Record<string, unknown>): Promise<ToolResult>;
  };

  on(event: "stateChange", handler: (state: ClientState) => void): () => void;
  on(event: "error", handler: (error: KontextError) => void): () => void;

  readonly mcp: KontextMcp;
}
```

## ClientState

```typescript theme={"system"}
type ClientState = "idle" | "connecting" | "ready" | "needs_auth" | "failed";
```

| State        | Meaning                                               |
| ------------ | ----------------------------------------------------- |
| `idle`       | Client created, not yet connected.                    |
| `connecting` | Connection in progress.                               |
| `ready`      | Connected and authenticated. Tools are available.     |
| `needs_auth` | User needs to sign in before connecting.              |
| `failed`     | Connection failed. Check the error event for details. |

## KontextTool

A tool discovered through the client SDK.

```typescript theme={"system"}
interface KontextTool {
  id: string;
  name: string;
  description?: string;
  inputSchema?: object;
  server?: { id: string; name?: string };
}
```

The `server` field is present in hybrid mode, indicating which integration the tool belongs to. In single-endpoint mode, all tools come from one server and this field is omitted.

## ToolResult

Result from `client.tools.execute()`.

```typescript theme={"system"}
interface ToolResult {
  content: string;
  raw: unknown;
}
```

`content` is the text representation. `raw` contains the full MCP `CallToolResult` response.

## IntegrationInfo

Integration status from `client.integrations.list()`.

```typescript theme={"system"}
interface IntegrationInfo {
  id: string;
  name: string;
  connected: boolean;
  connectUrl?: string;
  reason?: string;
}
```

When `connected` is `false`, `connectUrl` may provide a Kontext manage/connect URL so the user can finish required auth. This can be OAuth or API key (`user_token`) setup. See [Tools](/client/tools) for handling disconnected integrations.

## KontextStorage

Token persistence interface. Implement this to store tokens outside of memory.

```typescript theme={"system"}
interface KontextStorage {
  getJson<T>(key: string): Promise<T | undefined>;
  setJson<T>(key: string, value: T | undefined): Promise<void>;
}
```

The default `MemoryStorage` resets on page reload. See [Storage](/client/storage) for custom implementations.

## ConnectSessionResult

Returned by `client.getConnectPageUrl()`.

```typescript theme={"system"}
interface ConnectSessionResult {
  connectUrl: string;
  sessionId: string;
  expiresAt: string;
}
```