Skip to main content

​
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;
}
OptionTypeDescription
clientIdstringYour application’s OAuth client ID.
redirectUristringWhere to redirect after OAuth. Must match your application’s registered URI.
urlstring?MCP server endpoint for single-endpoint mode. Omit for hybrid/orchestrated mode.
serverUrlstring?Kontext API base URL. Defaults to https://api.kontext.dev.
storageKontextStorage?Token persistence backend. Defaults to MemoryStorage.
sessionKeystring?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) => voidCalled when an integration needs connecting. Show the connect URL to the user.
onStateChange(state) => voidCalled 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";
StateMeaning
idleClient created, not yet connected.
connectingConnection in progress.
readyConnected and authenticated. Tools are available.
needs_authUser needs to sign in before connecting.
failedConnection 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;
}