MCP Authentication

Authenticate MCP server actions using the SuperTokens MCP plugin.

Overview

This guide explains how to authenticate Model Context Protocol (MCP) Servers using SuperTokens. For the public, read-only SuperTokens documentation MCP server, see Build with AI Tools. This guide is for MCP servers that you build and host. The instructions make use of the plugins functionality. It is a new way to abstract common functionalities into a reusable package.

Before you start

The MCP authentication flow complies with the OAuth2 specifications. This means that you will have to use the OAuth2 recipe in your configuration.

The functionality is only available alongside the node SDK at the moment. Keep in mind that the feature is currently in beta and might be subject to breaking changes.

Steps

1. Install the plugin

Add the supertokens-mcp-plugin package to your project.

npm i -s supertokens-mcp-plugin

yarn add supertokens-mcp-plugin

pnpm add supertokens-mcp-plugin

2. Add the MCP server

Use the SuperTokensMcpServer class when in your implementation. The class extends the base MCP server exposed by the @modelcontextprotocol/sdk, and adds custom authentication logic on top of it.

You can authorize the client requests in two different ways. By using the standard claim validators. Or you can write your own custom validation logic in the validateTokenPayload function.

The authentication state can be accessed inside a tool call through the second function argument, extra.authInfo.

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

const server = new SuperTokensMcpServer({
  name: "example-mcp",
  version: "1.0.0",
  path: "/mcp",
  validateTokenPayload: async (_accessTokenPayload, _userContext) => {
    // You can check the access token payload for any specific values
    return {
      status: "OK",
    };
  },
  // You can use claim validators to determine who can access the MCP server
  claimValidators: [UserRoleClaim.validators.includes("admin")],
});

server.registerTool(
  "session-info",
  {
    inputSchema: {},
    description: "Get session information",
  },
  async (_args, extra) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(extra.authInfo),
        },
      ],
    };
  },
);

3. Update the SDK initialization code

Now that you have created your server include it in the SuperTokens SDK configuration. This way, the SDK middleware will expose your new endpoint and authenticate each request.

import supertokens from "supertokens-node";
import OAuth2Provider from "supertokens-node/recipe/oauth2provider";
import SuperTokensMcpPlugin, { SuperTokensMcpServer } from "supertokens-mcp-plugin";

// The server that you have previously created
const server = new SuperTokensMcpServer({
  name: "example-mcp",
  version: "1.0.0",
  path: "/mcp",
});

supertokens.init({
  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(),
  ],
  experimental: {
    plugins: [
      SuperTokensMcpPlugin.init({
        mcpServers: [server],
      }),
    ],
  },
});