User Roles and Permissions
DeployStack uses a role-based system to control what different users can do in your installation. This guide explains how roles work and how to manage user access.
What are User Roles?
User roles determine what actions a person can perform in DeployStack. Think of roles as "job titles" that come with specific permissions. Each user is assigned one role that defines their level of access.
Available Roles
Global Administrator
Who needs this: The person responsible for managing the entire DeployStack installation.
What they can do:
- Manage all users (create, edit, delete)
- Configure global settings (email, authentication, system options)
- Manage roles and permissions
- Access all system features
- Manage all teams
- View MCP server credentials metadata across all teams (no credential values shown)
- MCP Catalog: Full management of global MCP servers and categories
- MCP Oversight: View all team MCP servers across the platform (read-only)
Important: The first person to register automatically becomes a Global Administrator.
Note: Global Administrators can see that teams have MCP server credentials but cannot view the actual credential values for security reasons.
Global User
Who needs this: Regular users who want to configure MCP servers.
What they can do:
- View and edit their own profile
- Create multiple teams
- Manage their own teams
- Configure MCP servers through their teams
- MCP Catalog: Browse and view global MCP servers only
Note: This is the default role for new users.
Team Administrator
Who needs this: Users who manage specific teams within the organization.
What they can do:
- Manage their team's settings
- View team members
- Add new members to their teams
- Change member roles (promote team_user to team_admin, or demote)
- Remove team members (except team owners)
- Transfer team ownership to another team member
- Manage team MCP server configurations
- Delete teams they own (except default teams)
- MCP Catalog: View global servers + full management of team MCP servers
Important: Team admins have full control over team membership and can manage all team members except the team owner.
Team Member Management Permissions
The following table shows exactly what each role can do with team member management:
| Action | team_user | team_admin | team_admin + owner | global_admin |
|---|---|---|---|---|
| List team members | ✅ (own teams) | ✅ (own teams) | ✅ (own teams) | ✅ (any team) |
| Add team member | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
| Remove team_user | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
| Remove team_admin | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
| Remove team owner | ❌ | ❌ | ❌ | ✅ (any team) |
| Promote to team_admin | ❌ | ✅ (non-default) | ✅ (non-default) | ✅ (any team) |
| Demote team_admin | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
| Transfer ownership | ❌ | ❌ | ✅ (non-default) | ✅ (any team) |
| Delete team | ❌ | ❌ | ✅ (non-default) | ✅ (non-default) |
Key Notes:
- Default teams are completely protected - no member management operations allowed
- Team admins can only manage team_users, not other team_admins or owners
- Team owners have full control over their teams (except default teams)
- Global admins can override most restrictions but still cannot modify default teams
MCP Catalog Permissions
The MCP (Model Context Protocol) Catalog has specific permissions based on your role:
| Role | Global Servers | Team Servers | Can Create | Can Edit | Can Delete | Categories |
|---|---|---|---|---|---|---|
| global_admin | ✅ View/Manage All | ✅ View All Teams | ✅ Global only | ✅ Global only | ✅ Global only | ✅ Full CRUD |
| team_admin | ✅ View only | ✅ View/Manage own team | ✅ Team only | ✅ Team only | ✅ Team only | ❌ View only |
| team_user | ✅ View only | ✅ View team servers | ❌ No | ❌ No | ❌ No | ❌ View only |
| global_user | ✅ View only | ❌ No access | ❌ No | ❌ No | ❌ No | ❌ View only |
MCP Catalog Notes:
- Global Servers: Community-wide MCP servers available to all users
- Team Servers: Private MCP servers visible only to team members
- Categories: Organizational categories for MCP servers (admin-managed)
- Global Admins: Can see all team servers for administrative oversight but cannot modify them
- Team Isolation: Teams can only manage their own servers, not other teams' servers
Team User
Who needs this: Basic team members who participate in MCP server configuration.
What they can do:
- View team information
- See team members
- Participate in team activities
- MCP Catalog: View global servers + view team MCP servers (read-only)
Limitations: Team users cannot add members, change roles, manage other team members, or create/edit MCP servers.
Understanding Teams
Teams are groups where users organize their MCP server configurations. Here's how teams work:
Team Basics
- Automatic Team: Every user gets their own default team when they register
- Multi-User Support: Teams support multiple members with role-based access control
- Team Owner: The person who created the team has full control
- Default Team Protection: Your personal default team cannot have additional members added
Team Management
- Create Teams: Use descriptive names for your different projects
- Team Settings: Customize team name and description
- Team Deletion: Only team owners can delete teams
Common Role Scenarios
Personal Use
- You are: Global Administrator (first user) or Global User
- Your teams: Use your default team for personal projects
- Additional teams: Create separate teams for different types of projects
Small Team
- Administrator: One person manages the system and users
- Team Members: Everyone else is a Global User who can join teams
- Collaboration: Users can collaborate within shared teams
Organization
- System Admin: Global Administrator manages the DeployStack installation
- Project Leads: Team Administrators manage specific project teams
- Developers: Global Users participate in team configurations
Managing User Roles
As a Global Administrator
To view all users:
- Go to User Management in your admin panel
- See list of all registered users with their roles
To change a user's role:
- Find the user in the user list
- Click on their role
- Select the new role from the dropdown
- Save changes
To create new users (if needed):
- Use the "Create User" option
- Fill in their information
- Assign appropriate role
- User receives login information
Managing Your Own Profile
All users can:
- View their profile information
- Update their name and email
- Change their password
- See their current role (but not change it)
Team Management
Creating Teams
- Go to Teams in your dashboard
- Click "Create Team"
- Enter team name and description
- Save - you become the team owner automatically
Managing Your Teams
- Edit team details: Update name and description
- View team information: See team settings and members
- Delete teams: Remove teams you no longer need
Team Limitations
- Default Team Protection: Your personal default team cannot have additional members
- Owner Control: Only team owners can modify team settings
Security and Access Control
What Roles Protect
- System Settings: Only administrators can change global configuration
- User Management: Only administrators can create, edit, or delete users
- Team Ownership: Only team owners can modify their teams
- Profile Privacy: Users can only edit their own profiles
Role Assignment Rules
- First User: Automatically becomes Global Administrator
- New Users: Get Global User role by default
- Self-Assignment: Users cannot change their own roles
- Admin Assignment: Only administrators can change user roles
Troubleshooting Roles and Teams
Can't Access Settings
Problem: "I don't see the Settings option" Solution: Only Global Administrators can access system settings. Contact your administrator.
Can't Create Teams
Problem: "Create Team button is disabled" Solution: Contact your administrator if you're unable to create teams.
Can't Change Role
Problem: "I want to be an administrator" Solution: Only existing administrators can assign roles. Ask your current administrator to change your role.
Lost Administrator Access
Problem: "No one has administrator access" Solution: This requires technical intervention. Contact your system administrator or technical support.
Best Practices
For Administrators
- Regular Review: Periodically review user roles and remove inactive users
- Principle of Least Privilege: Give users the minimum role needed for their tasks
- Documentation: Keep track of who has what role and why
- Backup Access: Ensure at least two people have administrator access
For Team Management
- Descriptive Names: Use clear team names that reflect their purpose
- Regular Cleanup: Delete teams you no longer use
- Organization: Consider how to organize your projects across teams
For Security
- Role Changes: Think carefully before changing someone's role
- Team Ownership: Be aware that team owners have full control over their teams
- Profile Information: Keep your profile information current
Getting Help
If you have questions about roles or teams:
- Role Questions: Contact your Global Administrator
- Technical Issues: Visit our Discord community
- Feature Requests: Let us know what team features you'd like to see
Remember: The role system is designed to be simple but secure. Most users will be happy as Global Users with their own teams, while administrators handle system-wide configuration.