---
title: MCP Authentication
description: Authenticate MCP server actions using the SuperTokens MCP plugin.
sidebar:
  badge: Beta
  order: 90
---

## 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](/integrate-with-ai). 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

<PaidFeatureCallout managedOnly />

The [MCP authentication flow](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) 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.

<CodeGroup group="package-managers">
<Tab title="npm" value="npm">
```bash
npm i -s supertokens-mcp-plugin
```
</Tab>
<Tab title="yarn" value="yarn">
```bash
yarn add supertokens-mcp-plugin
```
</Tab>
<Tab title="pnpm" value="pnpm">
```bash
pnpm add supertokens-mcp-plugin
```
</Tab>
</CodeGroup>


### 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](/additional-verification/session-verification/claim-validation).
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`.

```ts
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.

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