Scalekit

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Installation

Install the Scalekit plugin:

pnpm i @xmcp-dev/scalekit

For a complete working project, see the scalekit-http example.

Scalekit Setup

Before getting started, configure your Scalekit environment:

1. Go to your Scalekit Dashboard.
2. Navigate to Auth for SaaS → MCP Auth and register a new MCP server resource.
3. Go to Settings → API Credentials and save your Environment URL, Client ID, and Client Secret.

Scalekit automatically enables Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD) for MCP clients — no extra configuration needed.

Environment Variables

Create a .env file in the root of your project and configure the following environment variables:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=skc_...
SCALEKIT_CLIENT_SECRET=skcs_...

BASE_URL=http://127.0.0.1:3001

Set up the Provider

Create a middleware.ts and import the provider from the package:

import { scalekitProvider } from "@xmcp-dev/scalekit";

export default scalekitProvider({
  environmentUrl: process.env.SCALEKIT_ENVIRONMENT_URL!,
  clientId: process.env.SCALEKIT_CLIENT_ID!,
  clientSecret: process.env.SCALEKIT_CLIENT_SECRET!,
  baseURL: process.env.BASE_URL!,
});

Configuration Options

• environmentUrl: Your Scalekit environment URL from the dashboard.
• clientId: Scalekit client ID for OAuth.
• clientSecret: Scalekit client secret for SDK access.
• baseURL: Base URL of your MCP server.
• resourceId: (Optional) Scalekit resource ID for resource-specific OAuth metadata.
• scopes: (Optional) Array of scopes to advertise in resource metadata.
• docsURL: (Optional) URL for your MCP server documentation.

Get a user session

Access the authenticated user in your xmcp tools using getSession.

Example: Greet the user with their Scalekit identity

import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";
import { getSession } from "@xmcp-dev/scalekit";

export const schema = {
  name: z.string().optional().describe("The name of the user to greet"),
};

export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user with their Scalekit identity",
};

export default function greet({ name }: InferSchema<typeof schema>): string {
  const session = getSession();
  const displayName = name ?? session.userId;
  return `Hello, ${displayName}! Your user ID is ${session.userId}`;
}

Get user info

Access the full session including organization context.

Example: Return session details

import type { ToolMetadata } from "xmcp";
import { getSession } from "@xmcp-dev/scalekit";

export const metadata: ToolMetadata = {
  name: "whoami",
  description: "Returns the authenticated user's session information",
};

export default function whoami(): string {
  const session = getSession();
  return JSON.stringify(
    {
      userId: session.userId,
      organizationId: session.organizationId,
      scopes: session.scopes,
      expiresAt: session.expiresAt.toISOString(),
    },
    null,
    2
  );
}

The session object contains token data and user claims:

• session.userId: User ID (subject claim).
• session.scopes: Array of granted scopes.
• session.organizationId: Organization ID, if present.
• session.expiresAt: Token expiration as a Date.
• session.issuedAt: Token issue time as a Date.
• session.claims: Raw JWT claims for advanced use cases.

Access the client

The getClient() function gives you access to the full Scalekit Node SDK, allowing you to leverage all Scalekit features in your MCP tools.

Example: Get organization details

import { type ToolMetadata } from "xmcp";
import { getSession, getClient } from "@xmcp-dev/scalekit";

export const metadata: ToolMetadata = {
  name: "get-org",
  description: "Get the user's organization details",
};

export default async function getOrg(): Promise<string> {
  const session = getSession();
  const client = getClient();

  if (!session.organizationId) {
    return "No organization associated with this session.";
  }

  const { organization } = await client.organization.getOrganization(
    session.organizationId
  );

  return JSON.stringify(organization, null, 2);
}

Troubleshooting

Token Expired Errors

Access tokens are short-lived. If you see token_expired errors:

• MCP clients should automatically refresh tokens.
• If errors persist, the client may have a bug or the refresh token expired.
• Users can disconnect and reconnect to get fresh tokens.

Session Not Initialized

If you see Session not initialized errors:

• Ensure getSession is called within a tool or handler that runs through the middleware pipeline.
• Verify the scalekitProvider middleware is properly configured in your middleware.ts.
• Make sure the route is under the /mcp path.
• Check that the request includes a valid bearer token.

JWKS Resolution Failures

If token verification fails with network errors:

• Verify SCALEKIT_ENVIRONMENT_URL is correct and reachable.
• The plugin auto-discovers JWKS keys from the OIDC configuration endpoint.
• Check that your server can reach {environmentUrl}/.well-known/openid-configuration.

Invalid Token Errors

If tokens are consistently invalid:

• Verify SCALEKIT_ENVIRONMENT_URL matches your Scalekit environment.
• Check that the MCP server URL in your Scalekit dashboard matches BASE_URL.
• Ensure the token was issued for the correct resource.