SuperTokens MCP Plugin

Table of Contents

• Installation
• Usage

Installation

npm install --save supertokens-mcp-plugin

Usage

Integrating MCP server with the application

Create an MCP server

Create SuperTokensMcpServer

import { SuperTokensMcpServer } from "supertokens-mcp-plugin";

const mcpServer = new SuperTokensMcpServer({
  name: "demo-server",
  version: "1.0.0",

  // Supertokens specific
  path: "/mcp", // Endpoint where the mcp will be available

  // There are two ways to validate the mcp request
  // 1.
  validateTokenPayload: (accessTokenPayload, userContext) => {
    // Validate access to the MCP based on the `accessTokenPayload`
    return { status: "OK" };
    // or return { status: "ERROR", message: "error message" }
    // returning error will result in 403 Forbidden
  },

  // 2.
  claimValidators: [
    // Standard Supertokens Session claim validators such as...
    UserRoleClaim.validators.includes("admin"),
  ],
});

Register MCP tools

mcpServer
  .registerTool
  // ... standard MCP tool registration
  ();

You can also expose each tool as a POST API by doing the following:

mcpServer.registerToolWithAPI(
  "tool-name",
  "/api/tool-name"
  // ... rest of the standard MCP tool parameters
);

Enable the MCP Plugin

Finally include the MCP Plugin in the Supertokens.init

import SuperTokensMcpPlugin from "supertokens-mcp-plugin";
import SuperTokens from "supertokens-node";

SuperTokens.init({
  // ... supertokens config
  experimental: {
    plugins: [
      SuperTokensMcpPlugin.init({
        mcpServers: [mcpServer],
      }),
    ],
  },
});

Note: OAuth2Provider recipe must be initialised for the MCP authentication to work.

Admin Server

You can use the Admin MCP server in two ways:

• over HTTP, as an endpoint exposed by your current server
• as a CLI script, over STDIO

Using HTTP

1. Install the plugin

npm install --save supertokens-mcp-plugin

2. Update the SDK configuration

import UserRoles, { UserRoleClaim } from "supertokens-node/recipe/userroles";
import OAuth2Provider from "supertokens-node/recipe/oauth2provider";
import SuperTokensMcpPlugin, {
  SuperTokensAdminMcpServer,
} from "supertokens-mcp-plugin";

const adminMcpServer = new SuperTokensAdminMcpServer({
  path: "/mcp/admin",
  validateTokenPayload: async (accessTokenPayload) => {
    // Use custom logic to authenticate who can access the admin MCP server
    return { status: "OK" };
  },
  claimValidators: [UserRoleClaim.validators.includes("admin")],
});

export const SuperTokensConfig = {
  supertokens: {
    connectionURI: "<SUPERTOKENS_CONNECTION_URI>",
    apiKey: "<SUPERTOKENS_API_KEY>",
  },
  appInfo: {
    appName: "<APP_NAME>",
    apiDomain: "<API_DOMAIN>",
    websiteDomain: "<WEBSITE_DOMAIN>",
    apiBasePath: "<API_BASE_PATH>",
    websiteBasePath: "<WEBSITE_BASE_PATH>",
  },
  recipeList: [
    // Include your existing recipes here
    // The OAuth2Provider recipe is required for the MCP authorization process
    OAuth2Provider.init(),
  ],
  // Pass the MCP server through the plguin configuration section
  experimental: {
    plugins: [
      SuperTokensMcpPlugin.init({
        mcpServers: [adminMcpServer],
      }),
    ],
  },
};

3. Add the MCP server in a client configuration

{
  "mcpServers": {
    "server-with-authentication": {
      "command": "npx",
      "args": ["mcp-remote", "<API_DOMAIN>/mcp/admin"]
    }
  }
}

Using STDIO

You can run it directly through npx. You have to provide a set of environment variables that match the SDK configuration values. Here's an example configuration for Claude Desktop:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "supertokens-mcp-plugin", "--stdio"],
      "env": {
        "APP_NAME": "<APP_NAME>",
        "API_DOMAIN": "<API_DOMAIN>",
        "WEBSITE_DOMAIN": "<WEBSITE_DOMAIN>",
        "API_BASE_PATH": "<API_BASE_PATH>",
        "WEBSITE_BASE_PATH": "<WEBSITE_BASE_PATH>",
        "CONNECTION_URI": "<CONNECTION_URI>",
        "API_KEY": "<API_KEY>"
      }
    }
  }
}

Add the snippet to your claude_desktop_config.json file.