Scalekit Authentication

An authenticated MCP server using Scalekit for per-user and per-organization access.

Features

• Scalekit OAuth 2.1 via the official @xmcp-dev/scalekit plugin
• Per-user and per-organization session via getSession()
• RBAC support using permissions from the access token
• Example tools: whoami, save_note, list_my_notes (demonstrating isolation)
• HTTP transport with middleware-based auth
• Works with Cursor, Claude Code, Claude Desktop, and other MCP clients

Getting Started

Prerequisites

You need a Scalekit account with:

• An MCP server resource registered in the dashboard
• Dynamic Client Registration enabled

1. Create the project

npx create-xmcp-app --example scalekit

2. Environment setup

cp .env.example .env

Edit .env with your Scalekit credentials:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=skc_...
SCALEKIT_CLIENT_SECRET=skcs_...
SCALEKIT_RESOURCE_ID=res_...
BASE_URL=http://127.0.0.1:3001

3. Install & run

pnpm install
pnpm dev

How It Works

1. MCP clients send requests with Authorization: Bearer <token> header
2. The middleware verifies the JWT using Scalekit's JWKS
3. Valid sessions (including organization context) are stored in AsyncLocalStorage context
4. Tools access session data via getSession()

Using Session Data in Tools

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

export default function myTool() {
  const session = getSession();

  console.log(session.userId);
  console.log(session.organizationId);
  console.log(session.permissions);

  return `Hello from ${session.organizationId || 'unknown org'}!`;
}

Demonstrating Per-User and Per-Organization Isolation

This template includes example tools save_note and list_my_notes that scope data to the authenticated user and organization, with optional RBAC using permissions like notes:read and notes:write.

For a full test with multiple organizations, see the Scalekit Integration Guide.

RBAC with Permissions (Optional)

Scalekit can include permissions in the token. Enforce them in tools:

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

export default function saveNote({ content }: { content: string }) {
  const session = getSession();

  if (!session.permissions?.includes("notes:write")) {
    return "Missing notes:write permission.";
  }

  // ... save logic scoped to session.userId and session.organizationId
}

OAuth Endpoints

The plugin automatically registers:

• GET /.well-known/oauth-protected-resource — Resource server metadata
• GET /.well-known/oauth-authorization-server — Authorization server metadata

Deploy

pnpm build
node dist/http.js

Learn More

• xmcp Documentation
• Scalekit Integration Guide
• Scalekit MCP Auth Quickstart