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

# Helpers

> Low-level MCP client, error types, token verification, and OAuth helpers.

## Low-level MCP client

```typescript theme={"system"}
import { KontextMcp } from "@kontext-dev/js-sdk/mcp";
import open from "open";

declare function waitForCallbackUrl(): Promise<string>;

const mcp = new KontextMcp({
  clientId: "app_your-app-id",
  redirectUri: "http://localhost:3333/callback",
  onAuthRequired: async (url) => {
    await open(url.toString());
    return await waitForCallbackUrl();
  },
});

const tools = await mcp.listTools();
if (tools.length > 0) {
  const result = await mcp.callTool(tools[0]!.name, {});
}
```

Direct MCP protocol client with OAuth handling. Most applications should use `createKontextClient` instead -- this is for advanced use cases where you need raw MCP transport control.

### Methods

| Method                      | Returns                               | Description                                   |
| --------------------------- | ------------------------------------- | --------------------------------------------- |
| `listTools()`               | `Promise<Tool[]>`                     | List available MCP tools.                     |
| `callTool(name, args?)`     | `Promise<CallToolResult>`             | Execute a tool by name.                       |
| `handleCallback(url)`       | `Promise<void>`                       | Complete the OAuth callback.                  |
| `disconnect()`              | `Promise<void>`                       | Close the MCP connection.                     |
| `clearAuth()`               | `Promise<void>`                       | Remove stored tokens.                         |
| `isCallback(url)`           | `boolean`                             | Check if a URL is an OAuth callback.          |
| `createConnectSession()`    | `Promise<ConnectSessionResult>`       | Create a connect page session.                |
| `listRuntimeIntegrations()` | `Promise<RuntimeIntegrationRecord[]>` | List available integrations and their status. |

### Properties

| Property      | Type      | Description                           |
| ------------- | --------- | ------------------------------------- |
| `isConnected` | `boolean` | Whether the MCP connection is active. |
| `sessionId`   | `string?` | Current session ID, if connected.     |

### Runtime integration shape

`listRuntimeIntegrations()` returns records with explicit connect semantics:

```typescript theme={"system"}
type RuntimeIntegrationConnectType =
  | "oauth"
  | "user_token"
  | "credentials"
  | "none";

interface RuntimeIntegrationRecord {
  id: string;
  name: string;
  url: string;
  category: "gateway_remote_mcp" | "internal_mcp_credentials";
  connectType: RuntimeIntegrationConnectType;
  authMode?: "oauth" | "user_token" | "server_token" | "none";
  tokenLabel?: string;
  tokenHelpUrl?: string;
  tokenPlaceholder?: string;
  connection?: {
    connected: boolean;
    status: "connected" | "disconnected";
    expiresAt?: string;
    displayName?: string;
    lastVerifiedAt?: string;
    lastVerifiedStatus?: string;
    verificationMessage?: string;
  };
}
```

For `connectType: "user_token"`, prompt the user to provide an API key/token in the connect UI flow.

For admin-managed shared tokens, the runtime record uses `connectType: "none"` together with `authMode: "server_token"`. Treat these as read-only runtime entries: there is nothing for the end user to connect.

The runtime integration parser is strict: unknown or missing `connectType` values throw `kontext_runtime_integrations_invalid_response`.

## Error types

```typescript theme={"system"}
import {
  KontextError,
  translateError,
  isKontextError,
  isNetworkError,
  isUnauthorizedError,
} from "@kontext-dev/js-sdk/errors";

if (isKontextError(err)) {
  console.log(err.code, err.statusCode);
}
```

See [Errors](/errors) for the full error hierarchy, error codes, and handling patterns.

### Error classes

| Class                                | Typical code                                                     | Description                                                             |
| ------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `AuthorizationRequiredError`         | `kontext_authorization_required`                                 | User needs to sign in.                                                  |
| `IntegrationConnectionRequiredError` | `kontext_integration_connection_required`                        | Integration needs user connection (OAuth or API key). Has `connectUrl`. |
| `OAuthError`                         | varies (for example `kontext_oauth_token_exchange_failed`)       | OAuth flow failed.                                                      |
| `ConfigError`                        | varies (for example `kontext_config_missing_client_id`)          | SDK misconfiguration.                                                   |
| `NetworkError`                       | `kontext_network_error`                                          | Connection failure.                                                     |
| `HttpError`                          | varies (for example `kontext_not_found`, `kontext_rate_limited`) | HTTP error with status code.                                            |

### Type guards

| Function                   | Checks                                          |
| -------------------------- | ----------------------------------------------- |
| `isKontextError(err)`      | Any `KontextError` subclass.                    |
| `isNetworkError(err)`      | Network-level failures (DNS, timeout, refused). |
| `isUnauthorizedError(err)` | 401 responses.                                  |

### Error translation

`translateError(err)` normalizes MCP JSON-RPC errors, Streamable HTTP failures, unauthorized responses, and browser/network failures into `KontextError` subclasses or `kontext_*` codes.

Use it when you are working directly with `KontextMcp`, raw MCP SDK errors, or custom wrappers and want the same classification behavior as the higher-level client/orchestrator.

## Token verification

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

const verifier = new KontextTokenVerifier({
  jwksUrl: "https://api.kontext.security/.well-known/jwks.json",
  issuer: "https://api.kontext.security/",
  audience: "https://api.kontext.security/mcp",
});

const result = await verifier.verify(token);
if (result.success) {
  console.log(result.claims.clientId, result.claims.scopes);
} else {
  console.error(result.error.code, result.error.message);
}
```

Standalone token verification for custom middleware or non-Express servers. The server SDK uses this internally -- you only need this if you are building your own transport layer.

### Additional methods

| Method                | Returns                                | Description                                                                                |
| --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `verifyOrNull(token)` | `Promise<VerifiedTokenClaims \| null>` | Returns claims if valid, `null` if invalid. Simpler API when you don't need error details. |
| `clearCache()`        | `void`                                 | Clear the JWKS cache, forcing a fresh fetch on next verification.                          |

## OAuth utilities

```typescript theme={"system"}
import { parseOAuthCallback, exchangeToken } from "@kontext-dev/js-sdk/oauth";

const { code, state, error } = parseOAuthCallback(
  "http://localhost:3333/callback?code=abc&state=xyz",
);

const exchanged = await exchangeToken(
  {
    tokenUrl: "https://api.kontext.security/oauth2/token",
    clientId: "app_or_mcp_client_id",
    clientSecret: process.env.KONTEXT_CLIENT_SECRET,
  },
  "subject_token_here",
  "mcp-gateway",
);
```

Low-level OAuth helpers for building custom flows. Most applications should use `createKontextClient` or the React adapter, which handle OAuth automatically.