npm install --save supertokens-mcp-plugin
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.
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
- Install the plugin
npm install --save supertokens-mcp-plugin
- 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],
}),
],
},
};
- Add the MCP server in a client configuration
{
"mcpServers": {
"server-with-authentication": {
"command": "npx",
"args": ["mcp-remote", "<API_DOMAIN>/mcp/admin"]
}
}
}
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.