Tools - Kontext

List tools

client.tools.list() returns every tool available to your application. Each tool has an id, name, optional description, and optional inputSchema describing its parameters.

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

for (const tool of tools) {
  console.log(tool.id, tool.description);
}

Tool ID format depends on where the tool comes from:

Gateway-routed tools keep the ID returned by the gateway.
Direct internal integration tools are normalized as <integrationId>:<toolName>.
Single-endpoint mode usually uses the MCP server’s tool names.

Always execute tools by IDs returned from tools.list(). The limit option caps the gateway discovery query. It only applies in gateway mode; in other modes the parameter is ignored and all tools are returned.

const tools = await client.tools.list({ limit: 10 });

Execute a tool

client.tools.execute(toolId, args) runs a tool and returns a ToolResult with a content string and the raw MCP response.

const [firstTool] = await client.tools.list();
if (!firstTool) throw new Error("No tools available");

const result = await client.tools.execute(firstTool.id, {});

console.log(result.content);

Full example

import { createKontextClient } from "@kontext-dev/js-sdk/client";

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

await client.connect();

// Discover available tools
const tools = await client.tools.list();
console.log(`Found ${tools.length} tools`);

// Execute one
if (tools.length > 0) {
  const result = await client.tools.execute(tools[0].id, {});
  console.log(result.content);
}

await client.disconnect();

Check integrations

client.integrations.list() returns the status of every integration attached to your application. Each entry tells you whether the user has connected that integration.

const integrations = await client.integrations.list();

for (const integration of integrations) {
  console.log(integration.name, integration.connected);
}

Handle disconnected integrations

When connected is false, the IntegrationInfo object may include a connectUrl you can open so the user can complete connection steps. This can be OAuth authorization or API key (user_token) setup. It may also include a reason explaining why the integration is not connected.

const integrations = await client.integrations.list();
const disconnected = integrations.filter((i) => !i.connected);

for (const integration of disconnected) {
  console.log(`${integration.name}: ${integration.reason}`);
  if (integration.connectUrl) {
    // Open this URL for the user to complete connection
    window.open(integration.connectUrl);
  }
}

You can also handle this reactively through the onIntegrationRequired callback, which fires when a tool call fails because the integration is not connected:

const client = createKontextClient({
  clientId: "your-client-id",
  redirectUri: "http://localhost:3000/callback",
  onAuthRequired: (url) => { window.location.href = url.toString(); },
  onIntegrationRequired: (url, info) => {
    console.log(`Please connect ${info.name}`);
    window.open(url);
  },
});

Tool shape reference

interface KontextTool {
  id: string;            // Unique tool identifier for this client runtime
  name: string;          // Display name
  description?: string;  // What the tool does
  inputSchema?: object;  // JSON Schema for the tool's arguments
  server?: {             // Present in hybrid mode
    id: string;
    name?: string;
  };
}

interface ToolResult {
  content: string;  // Extracted text content
  raw: unknown;     // Full MCP response
}

Next steps

Authentication — OAuth sign-in, callbacks, and session management.
Storage — Persist tokens across sessions with custom backends.
Client Types — Full type reference for KontextClient, KontextTool, and ToolResult.

​List tools

​Execute a tool

​Full example

​Check integrations

​Handle disconnected integrations

​Tool shape reference

​Next steps