Client Types - Kontext

createKontextClient

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 for the full usage guide.

KontextClientConfig

Configuration passed to createKontextClient.

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.

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

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.

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

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

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 for handling disconnected integrations.

KontextStorage

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

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 for custom implementations.

ConnectSessionResult

Returned by client.getConnectPageUrl().

interface ConnectSessionResult {
  connectUrl: string;
  sessionId: string;
  expiresAt: string;
}

​createKontextClient

​KontextClientConfig

​KontextClient

​ClientState

​KontextTool

​ToolResult

​IntegrationInfo

​KontextStorage

​ConnectSessionResult