# SuperTokens MCP

> SuperTokens manages your application’s entire identity layer directly through an AI agent connection. It provides tools for user signup, sign-in, session control (create/refresh/revoke), Role-Based Access Control (RBAC) management, and account linking. You manage who can do what—from creating tenants to assigning roles—all via natural language prompts.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** authentication, session-management, rbac, jwt, user-lifecycle, security

## Description

Listen up. This server handles your application's whole identity layer—everything from sign-up to session termination and permissions. You run this through your AI client, and it gives you tools for managing user lifecycles, securing sessions, and handling Role-Based Access Control (RBAC) without ever having to write manual backend code yourself.

When you're setting up a new user identity, you can register someone completely fresh using `signup_user`. If the person already exists but you need their full profile details, you just call `get_user` and grab everything. You don't wanna do it one by one though; if you got a bunch of accounts to onboard, you use `bulk_import_users` to dump them into the system using provided data sets.

If a user account is active but you need to wipe out some specific, non-core tracking info—say, old preferences or temporary flags—you can run `delete_user_metadata`. Conversely, if you gotta write new custom key/value metadata for a profile, you use `update_user_metadata`, and if you just wanna peek at what's stored there without touching the core user data, you call `get_user_metadata`.

Keeping users logged in is all about sessions. When they first log in with their credentials, you run `signin_user` to authenticate them and start a brand new session token. If they're still browsing but haven't done anything that requires re-login, you extend the lifespan of their current access using `refresh_session`. But if things go sideways, or they just logged out, you immediately invalidate all access by calling `remove_session` on their specific user ID. To start them from scratch, you can also manually create a brand new authenticated session token for any given user ID with `create_session`.

Permissions—that's where the real power is. You define what people are allowed to do using roles. First, you check out all available roles by calling `list_roles`. If you need to build a whole new permission tier or tweak an existing one, you use `create_or_update_role` to set those rules and permissions. Once the role is solid, you assign it directly to any user using `assign_role_to_user`. To see what permissions are currently assigned to a specific person, you check their list by running `list_user_roles`. The whole system works so you can manage who has access without touching database queries.

For account integrity, sometimes users have multiple IDs tied together. You connect two separate accounts that used to be floating around using `link_accounts` to tie them into one primary identity. If the user needs to break up those connections—maybe they started a new profile or something—you run `unlink_accounts` and restore them to independent profiles.

This server also handles isolated environments, so if you're dealing with multiple clients or tenants, you can get the full configuration and details of an existing tenant environment by calling `get_tenant`, or you can set up a whole new sandboxed area for a client using `create_or_update_tenant`.

It’s seriously comprehensive. You manage everything from user creation (`signup_user`), to fetching core data (`get_user`), to managing complex permissions and account linkages, all through simple prompts given to your AI agent.

## Tools

### assign_role_to_user
Assigns a defined role to an existing user account.

### bulk_import_users
Imports multiple users into the system using provided data sets.

### create_or_update_role
Creates a new user role or updates an existing one with defined permissions.

### create_or_update_tenant
Creates or modifies the isolated environment for a specific client tenant.

### create_session
Establishes a brand new authenticated session token for a user ID.

### delete_user_metadata
Removes custom metadata that was stored for a specific user account.

### get_tenant
Retrieves the full configuration and details of an isolated tenant environment.

### get_user
Fetches all core details for a user based on their unique ID.

### get_user_metadata
Reads and returns the custom key/value metadata associated with a user profile.

### link_accounts
Connects two separate, previously unconnected user accounts to one primary identity.

### list_roles
Returns a list of every role currently defined and available in the system.

### list_user_roles
Retrieves all roles that have been explicitly assigned to a specific user ID.

### refresh_session
Extends the lifespan of an existing, active user session token without re-login.

### remove_session
Immediately invalidates and revokes a specific user's active session or access token.

### signin_user
Authenticates an existing user using credentials and creates a new session.

### signup_user
Registers a completely new user account into the system.

### unlink_accounts
Separates two linked user accounts, restoring them to independent profiles.

### update_user_metadata
Writes or modifies custom key/value metadata for an existing user account profile.

## Prompt Examples

**Prompt:** 
```
Get details for user ID 'user-123'.
```

**Response:** 
```
I've retrieved the details for user 'user-123'. They are registered with email 'dev@example.com' and currently have 2 active sessions.
```

**Prompt:** 
```
Assign the 'editor' role to user 'user-456'.
```

**Response:** 
```
Successfully assigned the 'editor' role to 'user-456'. They now have the associated permissions for that role.
```

**Prompt:** 
```
List all available roles in the system.
```

**Response:** 
```
Here are the roles currently configured in your SuperTokens instance: 'admin', 'editor', and 'viewer'.
```

## Capabilities

### Manage User Identities
Create new users via `signup_user` or retrieve full profiles using `get_user`.

### Control Active Sessions
Generate a new session with `create_session`, refresh an old one with `refresh_session`, or immediately revoke access using `remove_session`.

### Define and Assign Roles (RBAC)
Use `create_or_update_role` to build roles and then assign them directly to users via `assign_role_to_user`.

### Audit Account Connections
Link separate user accounts together using `link_accounts` or break the connection apart with `unlink_accounts`.

### Store Custom User Data
Write and read custom JSON metadata for users by calling `update_user_metadata` or `get_user_metadata`.

## Use Cases

### The Locked-Out User
A support engineer gets a call from a user who can't access the dashboard. Instead of asking for screenshots, they prompt their agent: 'Check the session status for user ID 99.' The agent runs `get_user` and finds two active sessions; it then uses `remove_session` to kill the bad token, fixing the problem instantly.

### The New Client Tenant
A platform architect needs to onboard a new corporate client. They first run `create_or_update_tenant('AcmeCorp')`. Then, they use `signup_user` for the lead and immediately enforce least privilege by running `assign_role_to_user(lead, 'Viewer')` until full setup is complete.

### The Profile Merge
A user changes their email domain. The agent detects that two old accounts exist for the same person. Running `link_accounts` merges them under a new primary identity, and then running `update_user_metadata` ensures all profile details are consolidated.

### Security Audit Cleanup
A security analyst notices old roles are unused. They run `list_roles` to see everything defined, verify the permissions for each role, and then use `delete_user_metadata` on accounts that should no longer exist.

## Benefits

- **Immediate Access Control:** Don't manually jump between admin panels. You can assign or modify roles using `assign_role_to_user` instantly from your agent chat.
- **Session Auditing:** If a user reports suspicious activity, you don't need the logs team. Use `get_user` and `remove_session` to check status and kill tokens immediately.
- **Data Persistence:** Need to track non-login data? Store application preferences or integration IDs using `update_user_metadata`. It keeps that custom JSON right next to user identity.
- **Account Consolidation:** A user might have old accounts. Use `link_accounts` so the AI agent can treat them as one profile, simplifying support tickets and access checks.
- **Scalable Onboarding:** Instead of manual CSV uploads, run `bulk_import_users` to onboard large groups while simultaneously defining their roles with `create_or_update_role`.

## How It Works

The bottom line is, you talk to your AI client, and it talks to SuperTokens on your behalf.

1. Subscribe to this server and provide your SuperTokens Core URL and API Key.
2. Your AI agent uses natural language prompts (e.g., 'Revoke the session for user X').
3. The MCP Server executes the corresponding tool function, making direct calls to your authentication backend.

## Frequently Asked Questions

**How do I assign roles using SuperTokens MCP Server?**
You use the `assign_role_to_user` tool. You simply tell your agent which role and which user ID you want to link up. It handles the backend logic.

**Can I check what roles a user has using SuperTokens MCP Server?**
Yes, use `list_user_roles`. This tool quickly retrieves all active roles assigned to a specific user ID so you can audit their access level.

**How do I end an old user session with SuperTokens MCP Server?**
You must call the `remove_session` tool. It revokes the token immediately, ensuring that even if the user tries to use a cached credential, their access fails.

**What is the difference between `get_user` and `get_user_metadata`?**
`get_user` pulls core identity data (email, ID). `get_user_metadata` reads custom JSON fields you added to track app-specific details.

**How do I use the `link_accounts` tool in SuperTokens MCP Server?**
The `link_accounts` tool merges two separate user identities into one primary profile. Use this when a user changes their login method or ID, ensuring all associated data stays correctly tied to a single master account.

**When should I use the `refresh_session` tool in SuperTokens MCP Server?**
You run `refresh_session` to extend an existing user's active session without forcing them to log back in. This keeps users logged in smoothly and prevents access issues caused by premature token expiration.

**When should I use `update_user_metadata` instead of updating core user details?**
Use `update_user_metadata` for non-critical, custom data like preferences or last viewed items. This keeps your calls targeted and efficient, avoiding unnecessary changes to the user's primary records.

**How does the `create_or_update_tenant` tool help manage multiple clients?**
This tool manages separate, isolated environments within SuperTokens Core. It lets you set up and maintain distinct data boundaries so one client's roles or users never mix with another tenant’s.

**Can I retrieve specific user information using their ID?**
Yes, by using the `get_user` tool with the specific User ID, you can fetch the full profile, including email and account linking status.

**How do I assign a specific role like 'admin' to a user?**
You can use the `assign_role_to_user` tool. Just provide the User ID and the role name to update their permissions immediately.

**Is it possible to update custom user data or preferences?**
Absolutely. The `update_user_metadata` tool allows you to pass a JSON object to store or update custom information for any user.