Authenticate MCP Servers

Overview

This guide explains how to authenticate Model Context Protocol (MCP) Servers using SuperTokens. The instructions make use of the plugins functionality. It is a new way to abstract common functionalities into a reusable package.

Before you start

This feature is only available to paid users.

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

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

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 UserRoles, { UserRoleClaim } from "supertokens-node/recipe/userroles";
import OAuth2Provider from "supertokens-node/recipe/oauth2provider";
import type { TypeInput } from "supertokens-node/types";
import { z } from "zod";
import SuperTokensMcpPlugin, {
  SuperTokensMcpServer,
} from "supertokens-mcp-plugin";
import SuperTokens from "supertokens-node";

const server = new SuperTokensMcpServer({
  name: "example-mcp",
  version: "1.0.0",
  path: "/mcp",
  validateTokenPayload: async (_accessTokenPayload, _userContext) => {
    // You can check the acccess token payload for any specific values
    return {
      status: "OK",
    };
  },
  // By default, you can use calim 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 SuperTokensMcpPlugin, {
  SuperTokensMcpServer,
} from "supertokens-mcp-plugin";

// The server that you have previously created
const server = new SuperTokensMcpServer({});

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],
      }),
    ],
  },
});