Skip to main content

​
Kontext

import { Kontext } from "@kontext-dev/js-sdk/server";

const kontext = new Kontext({ clientId: "mcp_your-server" });
app.use(kontext.middleware(() => createServer()));
The Kontext class is the entry point for the server SDK. See Server SDK for the full usage guide.

​
KontextOptions

Configuration for the Kontext constructor. 
interface KontextOptions {
  clientId: string;
  apiUrl?: string;
  clientSecret?: string;
  tokenIssuer?: string | string[];
}
OptionTypeDefaultDescription
clientIdstring—Your MCP server’s OAuth client ID.
apiUrlstring?"https://api.kontext.dev"Kontext API base URL.
clientSecretstring?KONTEXT_CLIENT_SECRET envClient secret for server-side token exchange.
tokenIssuerstring | string[]?KONTEXT_TOKEN_ISSUER envExpected token issuer(s) for verification.

​
MiddlewareOptions

Options passed to kontext.middleware(). 
interface MiddlewareOptions {
  mcpPath?: string;
  resourceServerUrl?: string;
  dangerouslyOmitAuth?: boolean;
  verifier?: OAuthTokenVerifier;
  metadataTransform?: (metadata: OAuthMetadata) => OAuthMetadata;
  onSessionInitialized?: (sessionId: string, authInfo?: AuthInfo, transport?: StreamableHTTPServerTransport) => void;
  onSessionClosed?: (sessionId: string) => void;
  bodyLimit?: string | number;
}
OptionTypeDefaultDescription
mcpPathstring?"/mcp"Path for the MCP transport endpoint.
resourceServerUrlstring?Auto-detectedPublic URL of your server. Required when behind a reverse proxy.
dangerouslyOmitAuthboolean?falseSkip token verification. Development only.
verifierOAuthTokenVerifier?Built-in JWKSCustom token verification logic.
metadataTransform(metadata) => metadata—Rewrite OAuth metadata URLs for proxy/gateway setups.
onSessionInitialized(sessionId, authInfo, transport) => void—Called when a new MCP session starts.
onSessionClosed(sessionId) => void—Called when a session disconnects.
bodyLimitstring | number?"1mb"Maximum request body size.
See Middleware for detailed usage and examples.

​
Methods

​
kontext.require()

Exchange either a Kontext user access token or a known external end-user ID for an integration credential. 
kontext.require(integration: string, token: string): Promise<IntegrationCredential>
kontext.require(integration: string, options: { userId: string }): Promise<IntegrationCredential>
Use the token overload when your MCP handler already has the authenticated user’s Kontext access token. Use the { userId } overload when your confidential server has external-auth mappings configured and already knows the caller’s external subject ID. This is the hard-cutover path for credential vault and shared server_token integrations. Both overloads throw IntegrationConnectionRequiredError when the integration is not connected. In { userId } mode, the error does not include a connectUrl because the SDK does not have a bearer token it can use to create a user-facing connect session. See Credentials.

​
kontext.requireCredentials()

Resolve per-user credentials for internal integrations that use credential schemas instead of OAuth. 
kontext.requireCredentials(integration: string, token: string): Promise<IntegrationResolvedCredentials>

​
kontext.middleware()

Create an Express router with OAuth metadata, MCP transport, and authentication. 
kontext.middleware(server: McpServer | (() => McpServer), options?: MiddlewareOptions): Router
Pass a factory function () => McpServer for concurrent session support. See Middleware.

​
kontext.destroy()

Clean up sessions and resources. Call this on shutdown in serverless environments. 
kontext.destroy(): Promise<void>

​
IntegrationCredential

Returned by kontext.require(). 
interface IntegrationCredential {
  accessToken: string;
  tokenType: string;
  authorization: string;
  expiresIn?: number;
  scope?: string;
  integration: string;
}
FieldTypeDescription
accessTokenstringRaw access token for the integration.
tokenTypestringToken type, typically "Bearer".
authorizationstringPre-formatted header value ("Bearer <token>"). Pass directly to Authorization.
expiresInnumber?Seconds until the token expires.
scopestring?Scopes granted by the integration.
integrationstringIntegration name this credential was issued for.

​
IntegrationResolvedCredentials

Returned by kontext.requireCredentials(). 
interface IntegrationResolvedCredentials {
  integration: string;
  integrationId: string;
  credentials: Record<string, string>;
}
The credentials map contains key-value pairs defined by the integration’s credential schema.