Build with AI Tools

Overview

If you plan on using large language models (LLMs) to assist in the process of integrating SuperTokens, the documentation exposes a set of helpers that can aid you.

Text documentation

You can access all the documentation as plain text markdown files by appending .md to the end of any URL or by using the Copy Markdown button, from the top right part of each page. For example, you can find the plain text version of this page at https://supertokens.com/docs/quickstart/build-with-ai-tools.md.

This plain text format is ideal for AI tools and agents as it:

• Contains fewer formatting tokens.
• Displays content that might otherwise be hidden in the HTML or JavaScript-rendered version (such as content in tabs).
• Maintains a clear markdown hierarchy that LLMs can easily parse and understand.
• Can be read in a paginated format using the offset and length query parameters.

/llms.txt

The documentation website hosts an /llms.txt file which instructs AI tools and agents on how to retrieve the plain text versions of our pages. The file follows an emerging standard for enhancing content accessibility to LLMs.

Additionally, to access the entire documentation content in a single page you can use the /llms-full.txt file. Keep in mind that this file is really large and might get ignored by LLMs. You can use the offset and length query parameters to paginate the content.

Model Context Protocol (MCP) Server

If you want to leverage the agentic capabilities of an LLM tool you can use the SuperTokens Model Context Protocol (MCP) server. The server exposes a set of tools which instruct the LLM on how to access and read the documentation as well as how to administer your authentication integration.

Installation

You can use the MCP server in two ways:

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

Using HTTP

1Install the plugin

npm i -s supertokens-mcp-plugin

2Update the SDK initialization code

Initialize and include the SuperTokensAdminMcpServer in your SDK configuration. You have to specify how the client will be authorized through either claim validators or through custom logic defined in the validateTokenPayload function.

import UserRoles, { UserRoleClaim } from "supertokens-node/recipe/userroles";
import OAuth2Provider from "supertokens-node/recipe/oauth2provider";
import OpenID from "supertokens-node/recipe/openid";
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],
      }),
    ],
  },
};

3Add the MCP server in a client configuration

Add the following to your ~/.cursor/mcp.json file. To learn more, see the Cursor documentation.

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

Using STDIO

If you plan on using the server locally you can run it directly through npx. You have to provide a set of environment variables that match the SDK configuration values.

Add the following to your ~/.cursor/mcp.json file. To learn more, see the Cursor documentation.

{
  "mcpServers": {
    "supertokens": {
      "command": "npx",
      "args": ["-y", "supertokens-mcp-plugin"],
      "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"
      }
    }
  }
}