diff --git a/docs/development/backend/database.mdx b/docs/development/backend/database.mdx
index 6546ea7..6ded987 100644
--- a/docs/development/backend/database.mdx
+++ b/docs/development/backend/database.mdx
@@ -147,6 +147,29 @@ import { drizzle } from 'drizzle-orm/better-sqlite3';
 import { drizzle } from 'drizzle-orm/libsql';
 ```
 
+### Database Connection Patterns
+
+When accessing the database in route handlers, always use `getDb()` to obtain the database connection dynamically:
+
+```typescript
+import { getDb } from '../../../db';
+import { YourService } from '../../../services/yourService';
+
+export default async function yourRoute(server: FastifyInstance) {
+  const db = getDb();
+  const yourService = new YourService(db);
+  // ... rest of route handler
+}
+```
+
+**Why this pattern is required:**
+- `server.db` may be `null` during certain initialization states
+- `getDb()` always returns the active database connection
+- This ensures consistent behavior across all endpoints
+- Other working endpoints already follow this pattern
+
+**Avoid:** Direct usage of `server.db` as it can cause "Cannot read properties of null" errors.
+
 ## Database Structure
 
 The database schema is defined in `src/db/schema.sqlite.ts`. This is the **single source of truth** for all database schema definitions and works across all supported database types.
diff --git a/docs/development/backend/events.mdx b/docs/development/backend/events.mdx
new file mode 100644
index 0000000..d964be2
--- /dev/null
+++ b/docs/development/backend/events.mdx
@@ -0,0 +1,90 @@
+---
+title: Global Event Bus
+description: Type-safe event system for decoupled communication between core systems and plugins in DeployStack.
+---
+
+# Global Event Bus
+
+The Global Event Bus enables decoupled communication between core systems and plugins through a type-safe event system. Core systems emit events when important actions occur, and plugins can react without direct coupling to business logic.
+
+## Overview
+
+Key features:
+- **Type Safety**: Full TypeScript integration with strongly-typed event data
+- **Plugin Isolation**: Secure event listener registration with error isolation
+- **Performance**: Fire-and-forget event processing
+- **Security**: Events cannot be intercepted or modified by plugins
+
+## Event Naming Convention
+
+Events follow the `domain.action` pattern, aligned with the permission structure:
+
+- `user.registered`, `user.login`, `user.logout`, `user.updated`, `user.deleted`
+- `team.created`, `team.updated`, `team.member_added`, `team.member_removed`
+- `settings.updated`, `settings.smtp_configured`, `settings.github_configured`
+- `mcp.server_installed`, `mcp.server_uninstalled`, `mcp.server_configured`
+
+## Event Data Structure
+
+```typescript
+interface EventData<T = any> {
+  userId?: string;
+  teamId?: string;
+  data: T;
+}
+
+interface EventContext {
+  db: AnyDatabase | null;
+  logger: FastifyBaseLogger;
+  user?: { id: string; email: string; roleId: string; };
+  request?: { ip: string; userAgent?: string; requestId: string; };
+  timestamp: Date;
+}
+```
+
+## Event Constants
+
+```typescript
+import { EVENT_NAMES } from '../events';
+
+EVENT_NAMES.USER_REGISTERED    // 'user.registered'
+EVENT_NAMES.TEAM_CREATED       // 'team.created'
+EVENT_NAMES.SETTINGS_UPDATED   // 'settings.updated'
+```
+
+## Usage in Core Routes
+
+Emit events after successful operations:
+
+```typescript
+// After successful user registration
+server.eventBus?.emitWithContext(
+  EVENT_NAMES.USER_REGISTERED,
+  { userId: newUser.id, data: { user: newUser, source: 'email_registration' } },
+  eventContext
+);
+```
+
+## Plugin Event Listeners
+
+Plugins register event listeners in their configuration:
+
+```typescript
+class EmailNotificationPlugin implements Plugin {
+  eventListeners: EventListeners = {
+    [EVENT_NAMES.USER_REGISTERED]: this.handleUserRegistered.bind(this)
+  };
+
+  private async handleUserRegistered(eventData: EventData, context: EventContext) {
+    await this.sendWelcomeEmail(eventData.data.user);
+  }
+}
+```
+
+For detailed plugin event listener examples, see the [Plugin System Documentation](/development/backend/plugins).
+
+## Available Events
+
+Events are emitted for user lifecycle (`user.*`), team management (`team.*`), settings changes (`settings.*`), and MCP operations (`mcp.*`). Each event includes relevant data and context.
+
+For complete event schemas and data structures, see the [event type definitions](https://github.com/deploystackio/deploystack/blob/main/services/backend/src/events/types.ts).
diff --git a/docs/development/backend/mcp-configuration-architecture.mdx b/docs/development/backend/mcp-configuration-architecture.mdx
new file mode 100644
index 0000000..cea646f
--- /dev/null
+++ b/docs/development/backend/mcp-configuration-architecture.mdx
@@ -0,0 +1,214 @@
+---
+title: MCP Configuration Architecture
+description: Developer guide to DeployStack's three-tier MCP server configuration system for arguments and environment variables.
+sidebar: MCP Configuration Architecture
+---
+
+# MCP Configuration Architecture
+
+DeployStack implements a sophisticated three-tier configuration architecture for managing MCP server command line arguments and environment variables. This system supports multi-user teams while maintaining clean separation between fixed template parameters, shared team settings, and individual user configurations.
+
+## Architecture Overview
+
+The three-tier system separates MCP server configuration into distinct layers:
+
+1. **Template Level** - Fixed arguments and schemas defined in the MCP catalog
+2. **Team Level** - Shared team configurations and credentials
+3. **User Level** - Personal configurations for individual team members
+
+This architecture solves the fundamental challenge of supporting multiple users within the same team installation while allowing individual customization.
+
+## Lock/Unlock Control System
+
+The system's core feature is sophisticated lock/unlock controls that determine configuration boundaries:
+
+**Global Administrator Controls:**
+- **Categorization**: Classify every config element as Template/Team/User configurable
+- **Lock States**: Set `default_team_locked` and `visible_to_users` controls
+- **Security Boundaries**: Define what can never be changed vs. team/user configurable
+
+**Team Administrator Controls:**
+- **Lock/Unlock Elements**: Control what users can modify within schema boundaries
+- **Credential Management**: Manage team secrets with visibility controls
+
+**Runtime Access:**
+- Users see only unlocked elements they can configure
+- Locked elements are inherited but not modifiable
+
+## Design Problem
+
+### The Multi-User Team Challenge
+
+Traditional MCP configurations assume a single user per installation. DeployStack's team-based approach requires supporting scenarios like:
+
+**Team Setup:**
+- Team: "DevOps Team" 
+- Members: User A, User B
+- Devices: Each user has laptop + desktop
+- Total Configurations: 4 different configurations for the same MCP server
+
+**User Requirements:**
+- User A needs access to `/Users/userA/Desktop`
+- User B needs access to `/Users/userB/Desktop` and `/Users/userB/Projects`
+- Both users share the same team API credentials
+- Each user may have different debug settings
+
+### Solution Architecture
+
+The three-tier system addresses this by:
+
+1. **Template Level**: Defines what arguments are fixed vs configurable
+2. **Team Level**: Manages shared credentials and team-wide settings
+3. **User Level**: Allows individual customization per user and device
+
+## Database Schema
+
+### Tier 1: MCP Catalog (`mcpServers`)
+
+The catalog defines the configuration structure for each MCP server type:
+
+```sql
+-- Template Level (with lock controls)
+template_args: text('template_args')         -- [{value, locked, description}]
+template_env: text('template_env')           -- Fixed environment variables
+
+-- Team Schema (with lock/visibility controls) 
+team_args_schema: text('team_args_schema')   -- Schema with lock controls
+team_env_schema: text('team_env_schema')     -- [{name, type, required, default_team_locked, visible_to_users}]
+
+-- User Schema
+user_args_schema: text('user_args_schema')   -- User-configurable argument schema
+user_env_schema: text('user_env_schema')     -- User-configurable environment schema
+```
+
+### Tier 2: Team Installation (`mcpServerInstallations`)
+
+Team installations manage shared configurations:
+
+```sql
+installation_name: text('installation_name') -- Team-friendly name
+team_args: text('team_args')                 -- Team-level arguments (JSON array)
+team_env: text('team_env')                   -- Team environment variables (JSON object)
+```
+
+### Tier 3: User Configuration (`mcpUserConfigurations`)
+
+Individual user configurations support multiple devices:
+
+```sql
+installation_id: text('installation_id')     -- References team installation
+user_id: text('user_id')                     -- User who owns this config
+device_name: text('device_name')             -- "MacBook Pro", "Work PC", etc.
+
+user_args: text('user_args')                 -- User arguments (JSON array)
+user_env: text('user_env')                   -- User environment variables (JSON object)
+```
+
+## Configuration Flow
+
+### Runtime Assembly
+
+### Configuration Schema Step
+
+Global administrators categorize configuration elements through the Configuration Schema Step:
+
+1. **Extract Elements**: Parse Claude Desktop config for all args and env vars
+2. **Categorize Each Element**: Assign to Template/Team/User tiers
+3. **Set Lock Controls**: Define `default_team_locked` and `visible_to_users`
+4. **Generate Schema**: Create the three-tier schema structure
+
+### Runtime Assembly
+
+At runtime, configurations are assembled by merging all three tiers with lock/unlock controls applied:
+
+```javascript
+const assembleConfiguration = (server, teamInstallation, userConfig) => {
+  const finalArgs = [
+    ...server.template_args.map(arg => arg.value), // Fixed template args
+    ...(teamInstallation.team_args || []),          // Team shared args
+    ...(userConfig.user_args || [])                 // User personal args
+  ];
+  
+  const finalEnv = {
+    ...(server.template_env || {}),                 // Fixed template env
+    ...(teamInstallation.team_env || {}),           // Team shared env
+    ...(userConfig.user_env || {})                  // User personal env
+  };
+  
+  return { args: finalArgs, env: finalEnv };
+};
+```
+
+## Service Layer
+
+### McpUserConfigurationService
+
+The service layer provides complete CRUD operations for user configurations:
+
+**Key Methods:**
+- `createUserConfiguration()` - Create new user config with validation
+- `getUserConfiguration()` - Retrieve user config with team access control
+- `updateUserConfiguration()` - Update with schema validation
+- `deleteUserConfiguration()` - Remove user config
+- `updateUserArgs()` - Partial update for arguments only
+- `updateUserEnv()` - Partial update for environment variables only
+
+**Security Features:**
+- Team-based access control
+- User isolation (users can only access their own configs)
+- Schema validation against server-defined schemas
+- Input sanitization and type checking
+
+## API Endpoints
+
+## API Endpoints
+
+Configuration management through REST API:
+
+- Team installations: `/api/teams/{teamId}/mcp/installations/`
+- User configurations: `/api/teams/{teamId}/mcp/installations/{installationId}/user-configs/`
+- Schema validation: Built into all endpoints
+
+## Schema Example
+
+Configuration schema with lock/unlock controls:
+
+```json
+{
+  "template_args": [
+    {"value": "-y", "locked": true, "description": ""},
+    {"value": "@modelcontextprotocol/server-memory", "locked": true, "description": ""}
+  ],
+  "team_env_schema": [
+    {
+      "name": "MEMORY_FILE_PATH",
+      "type": "string", 
+      "required": true,
+      "default_team_locked": true,
+      "visible_to_users": false
+    }
+  ],
+  "user_env_schema": [
+    {
+      "name": "DEBUG_MODE",
+      "type": "string",
+      "required": false,
+      "locked": false
+    }
+  ]
+}
+```
+
+
+
+## Related Documentation
+
+For specific implementation details:
+
+- [Backend API](/development/backend/api) - Complete API endpoint documentation
+- [Database Schema](/development/backend/database) - Database structure and relationships
+- [Teams](/teams) - Team management and structure
+- [MCP Configuration System](/mcp-configuration) - User-facing configuration guide
+- [MCP Installation](/mcp-installation) - Installation and team setup
+
+The three-tier configuration architecture provides a robust foundation for managing complex MCP server configurations in multi-user team environments while maintaining security, flexibility, and ease of use.
diff --git a/docs/development/backend/plugins.mdx b/docs/development/backend/plugins.mdx
index 1c80587..63851e4 100644
--- a/docs/development/backend/plugins.mdx
+++ b/docs/development/backend/plugins.mdx
@@ -419,6 +419,33 @@ async initialize(app: FastifyInstance, db: AnyDatabase | null) {
 }
 ```
 
+### Event Listeners
+
+Plugins can listen to system events and react to core application changes:
+
+```typescript
+import { EVENT_NAMES, type EventListeners } from '../events';
+
+class MyPlugin implements Plugin {
+  eventListeners: EventListeners = {
+    [EVENT_NAMES.USER_REGISTERED]: this.handleUserRegistered.bind(this),
+    [EVENT_NAMES.TEAM_CREATED]: this.handleTeamCreated.bind(this)
+  };
+
+  private async handleUserRegistered(eventData, context) {
+    // React to user registration
+    context.logger.info(`New user: ${eventData.data.user.email}`);
+  }
+
+  private async handleTeamCreated(eventData, context) {
+    // React to team creation
+    await this.setupTeamResources(eventData.data.team);
+  }
+}
+```
+
+For complete event documentation, see the [Global Event Bus](./events) guide.
+
 ### Access to Core Services
 
 Plugins receive access to:
@@ -428,6 +455,7 @@ Plugins receive access to:
 - **Logger** (`logger`) - For structured logging with plugin context
 - **Schema Access** - Access to the generated database schema including your tables
 - **Global Settings** - Plugins can define and access their own global settings
+- **Event System** - Listen to and react to core application events
 
 ## Plugin Lifecycle
 
diff --git a/docs/development/gateway/mcp.mdx b/docs/development/gateway/mcp.mdx
index dde34d6..73391e0 100644
--- a/docs/development/gateway/mcp.mdx
+++ b/docs/development/gateway/mcp.mdx
@@ -20,12 +20,20 @@ The Gateway implements a sophisticated MCP configuration system that:
 
 ## API Integration
 
-### Endpoint
-The Gateway fetches MCP installations from:
+### Legacy Team-Based Endpoint
+The Gateway can fetch MCP installations from the legacy team-based endpoint:
 ```
 GET /api/teams/{teamId}/mcp/installations
 ```
 
+### Modern Three-Tier Gateway Endpoint
+For optimal performance and device-specific configurations, the Gateway uses the modern three-tier endpoint:
+```
+GET /api/gateway/me/mcp-configurations?hardware_id={hardwareId}
+```
+
+This endpoint automatically merges Template + Team + User configurations and returns ready-to-use server configurations with device-specific user arguments and environment variables. For detailed information about this endpoint, see the [Backend API Documentation](/development/backend/api).
+
 ### Response Structure
 The API returns team MCP installations with this interface:
 ```typescript
diff --git a/docs/development/gateway/oauth.mdx b/docs/development/gateway/oauth.mdx
index fc807d1..c610dcc 100644
--- a/docs/development/gateway/oauth.mdx
+++ b/docs/development/gateway/oauth.mdx
@@ -59,16 +59,53 @@ The temporary callback server:
 - Displays a success or error page to the user
 - Automatically shuts down after receiving the callback
 
-### 4. Token Exchange
+### 4. Token Exchange with Device Registration
 
 After receiving the authorization code, the CLI:
 
+- Detects device information (hostname, OS, hardware fingerprint)
 - Exchanges the code for access and refresh tokens
 - Includes the PKCE code verifier for verification
+- **Automatically registers the device** during token exchange
 - Validates the token response from the backend
 - Fetches user information using the new access token
 - Stores credentials securely for future use
 
+#### Automatic Device Registration
+
+During the token exchange process, the gateway automatically registers the current device with the backend for security and management purposes:
+
+**Device Information Collected:**
+- `device_name`: User-friendly name (defaults to hostname)
+- `hostname`: System hostname
+- `hardware_id`: Unique hardware fingerprint based on MAC addresses and system info
+- `os_type`: Operating system (macOS, Windows, Linux)
+- `os_version`: OS version string
+- `arch`: System architecture (x64, arm64, etc.)
+- `node_version`: Node.js version for compatibility tracking
+- `user_agent`: CLI version and platform information
+
+**Security Benefits:**
+- Device registration happens only during authenticated login sessions
+- **No separate device registration endpoints exist** - this prevents unauthorized device registration and enhances security
+- Hardware fingerprinting provides unique device identification
+- Enables device management and access control in the backend
+- Eliminates the need for manual device registration API calls
+
+**Process Flow:**
+1. Gateway detects current device information using system APIs
+2. Device info is included in the OAuth2 token request
+3. Backend validates the token request and registers the device
+4. Device information is returned in the token response
+5. Gateway logs successful device registration to the user (e.g., "📱 Device registered: MacBook-Pro.local")
+
+**Error Handling:**
+If device registration fails during token exchange:
+- The OAuth2 login process continues successfully
+- User authentication is not affected
+- Device context may be limited for some features
+- Error is logged but doesn't break the login flow
+
 ## PKCE Security Implementation
 
 The gateway implements PKCE (Proof Key for Code Exchange) following RFC 7636:
@@ -198,6 +235,67 @@ The gateway OAuth client integrates with the [backend OAuth2 server](/developmen
 - **Token Format**: Handles backend's custom JWT-like token format
 - **Error Responses**: Processes standard OAuth2 error responses
 - **Endpoint Discovery**: Uses standard OAuth2 endpoint paths
+- **Device Registration**: Automatic device registration during token exchange
+
+### Device Management Integration
+
+The gateway's device registration integrates seamlessly with the backend's device management system:
+
+**Backend Integration Points:**
+- **OAuth2 Token Endpoint**: Extended to accept optional `device_info` in token requests
+- **Device Service**: Uses existing `DeviceService.registerOrUpdateDevice()` method
+- **Database Storage**: Device information stored in the `devices` table
+- **User Association**: Devices automatically linked to the authenticated user
+
+**Token Request Enhancement:**
+The gateway includes device information in the OAuth2 token request:
+```json
+{
+  "grant_type": "authorization_code",
+  "code": "authorization_code_here",
+  "redirect_uri": "http://localhost:8976/oauth/callback",
+  "client_id": "deploystack-gateway-cli",
+  "code_verifier": "pkce_verifier_here",
+  "device_info": {
+    "device_name": "MacBook-Pro.local",
+    "hostname": "MacBook-Pro.local",
+    "hardware_id": "a1b2c3d4e5f6789012345678901234ab",
+    "os_type": "macOS",
+    "os_version": "14.2.1",
+    "arch": "arm64",
+    "node_version": "v20.10.0",
+    "user_agent": "DeployStack-CLI/1.0.0 (darwin; arm64)"
+  }
+}
+```
+
+**Token Response Enhancement:**
+When device registration succeeds, the backend includes device information in the token response:
+```json
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "...",
+  "scope": "mcp:read account:read...",
+  "device": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "device_name": "MacBook-Pro.local",
+    "is_active": true,
+    "is_trusted": true,
+    "created_at": "2025-08-23T10:20:30Z"
+  }
+}
+```
+
+**Security Design:**
+- Device registration only occurs during authenticated OAuth2 flows
+- **No separate device creation endpoints exist** - this architectural decision prevents unauthorized device registration and eliminates potential security vulnerabilities
+- Hardware fingerprinting ensures unique device identification across multiple login sessions
+- Device information is validated using JSON schema before processing
+- Gateway automatically handles device lookup using hardware fingerprints without requiring manual registration
+
+For comprehensive information about device management and hardware fingerprinting, see the [Device Management Documentation](/device-management).
 
 ## Security Considerations
 
diff --git a/docs/device-management.mdx b/docs/device-management.mdx
new file mode 100644
index 0000000..94fbf89
--- /dev/null
+++ b/docs/device-management.mdx
@@ -0,0 +1,303 @@
+---
+title: Device Management
+description: Understand how DeployStack manages devices across your organization for security, compliance, and seamless multi-device MCP configuration workflows.
+sidebar: Device Management
+icon: Monitor
+---
+
+# Device Management
+
+DeployStack automatically tracks and manages devices across your organization to enable secure multi-device MCP configurations, enterprise governance, and seamless user experiences. Every device that accesses DeployStack is registered and managed through our comprehensive device management system.
+
+## Why Device Management Matters
+
+Device management is essential for DeployStack's three-tier MCP configuration system and enterprise security:
+
+**🏢 Enterprise Governance**
+- **Visibility**: Administrators can see which devices access which MCP servers across the organization
+- **Compliance**: Complete audit trails for regulatory requirements and security policies
+- **Access Control**: Ability to manage and revoke device access when needed
+- **Risk Management**: Identify and respond to unauthorized or compromised devices
+
+**👥 Team Collaboration**
+- **Multi-Device Workflows**: Users seamlessly work across laptops, desktops, and cloud workstations
+- **Device-Specific Configurations**: Different MCP settings for different environments (development vs. production machines)
+- **Team Visibility**: Team administrators can see device usage patterns and optimize configurations
+
+**🔒 Security & Trust**
+- **Device Authentication**: Each device is uniquely identified and authenticated
+- **Hardware Fingerprinting**: Secure device identification based on system characteristics
+- **Trust Management**: Mark devices as trusted or untrusted based on organizational policies
+- **Automatic Registration**: Devices are registered securely during OAuth2 login flow
+
+## How Device Registration Works
+
+Device registration happens automatically and securely during the CLI login process:
+
+### Automatic Registration Process
+
+1. **User Initiates Login**: User runs `deploystack login` command
+2. **OAuth2 Flow Begins**: Standard OAuth2 authorization with PKCE security
+3. **Device Detection**: Gateway automatically detects device information:
+   - Device name (hostname)
+   - Hardware fingerprint (unique identifier based on MAC addresses and system info)
+   - Operating system and version
+   - System architecture
+   - Node.js version for compatibility
+4. **Secure Registration**: Device info is included in OAuth2 token exchange
+5. **Backend Processing**: Device is registered or updated in the database
+6. **User Confirmation**: User sees "📱 Device registered: [device-name]" message
+
+### Security Benefits of Integrated Registration
+
+- **No Separate Endpoints**: Device registration only happens during authenticated login sessions
+- **OAuth2 Security**: Leverages existing OAuth2 security with PKCE
+- **Hardware Fingerprinting**: Unique device identification without user input
+- **Automatic Process**: No manual device management required
+
+For technical details on the OAuth2 integration, see [Gateway OAuth Implementation](/development/gateway/oauth#automatic-device-registration).
+
+## Device Information Collected
+
+DeployStack collects minimal device information necessary for identification and configuration management:
+
+**🔍 Device Identification**
+- **Device Name**: User-friendly name (defaults to hostname, can be customized)
+- **Hardware ID**: Unique fingerprint based on MAC addresses and system characteristics
+- **Hostname**: System hostname for identification
+
+**💻 System Information**
+- **Operating System**: Type and version (macOS, Windows, Linux)
+- **Architecture**: System architecture (x64, arm64, etc.)
+- **Node.js Version**: For compatibility tracking and troubleshooting
+- **User Agent**: CLI version and platform information
+
+**📊 Usage Metadata**
+- **Last Login**: When the device was last used for authentication
+- **Last Activity**: Most recent MCP server interaction
+- **Trust Status**: Whether the device is marked as trusted
+- **Active Status**: Whether the device is currently active
+
+## Multi-Device User Experience
+
+Users can seamlessly work across multiple devices with device-specific configurations:
+
+### Device-Specific MCP Configurations
+
+Each device maintains its own personal MCP configuration while inheriting team settings:
+
+**Example: Filesystem MCP Server**
+- **MacBook Pro**: `/Users/alice/Development`, `/Users/alice/Projects`
+- **Work Desktop**: `C:\Users\alice\Projects`, `C:\Company\Shared`
+- **Cloud Workstation**: `/home/alice/workspace`, `/data/projects`
+
+**Shared Team Settings** (inherited on all devices):
+- Team API keys and credentials
+- Shared project directories
+- Team-wide configuration standards
+
+### Device Management Interface
+
+Users can manage their devices through the DeployStack interface:
+
+```
+Your Devices
+
+📱 MacBook Pro (Current Device)
+   ├─ Last Login: 2 minutes ago
+   ├─ Status: Active, Trusted
+   ├─ MCP Configurations: 5 active
+   └─ [Configure] [View Details]
+
+🖥️ Work Desktop
+   ├─ Last Login: Yesterday
+   ├─ Status: Active, Trusted
+   ├─ MCP Configurations: 3 active
+   └─ [Configure] [View Details]
+
+☁️ Cloud Workstation
+   ├─ Last Login: 3 days ago
+   ├─ Status: Inactive
+   ├─ MCP Configurations: 2 configured
+   └─ [Configure] [Reactivate]
+```
+
+## Administrator Perspective
+
+### Enterprise Device Visibility
+
+Administrators have comprehensive visibility into device usage across the organization:
+
+**📊 Device Analytics Dashboard**
+- Total devices across all teams
+- Active vs. inactive device counts
+- Device types and operating systems
+- MCP server usage by device
+- Security alerts and untrusted devices
+
+**🔍 Device Search and Filtering**
+- Search by user, team, or device name
+- Filter by operating system, trust status, or activity
+- View device-specific MCP configurations
+- Export device reports for compliance
+
+### Security Management
+
+**🛡️ Device Trust Management**
+- Mark devices as trusted or untrusted
+- Automatically trust devices from known networks
+- Require manual approval for new devices
+- Bulk trust management for organizational devices
+
+**🚨 Security Monitoring**
+- Detect unusual device activity patterns
+- Alert on new device registrations
+- Monitor for potential security threats
+- Track device access to sensitive MCP servers
+
+**⚙️ Device Policies**
+- Set maximum devices per user
+- Require device naming conventions
+- Enforce device trust requirements
+- Configure automatic device cleanup policies
+
+## Team Administrator Perspective
+
+### Team Device Overview
+
+Team administrators can monitor device usage within their teams:
+
+**👥 Team Device Dashboard**
+- All devices used by team members
+- Device-specific MCP configuration usage
+- Team member device patterns
+- Device compliance with team policies
+
+**📈 Usage Analytics**
+- Which MCP servers are used on which devices
+- Device-specific configuration patterns
+- Team productivity insights
+- Resource utilization by device type
+
+### Device-Aware Configuration Management
+
+Team administrators can optimize configurations based on device usage:
+
+**💡 Configuration Insights**
+- See how team members configure MCP servers across different devices
+- Identify common device-specific patterns
+- Optimize team configurations for different device types
+- Provide device-specific guidance and templates
+
+## Security & Governance
+
+### Compliance Benefits
+
+**📋 Audit Trails**
+- Complete history of device access to MCP servers
+- Track configuration changes by device
+- Monitor team member device usage patterns
+- Generate compliance reports for auditors
+
+**🔐 Access Control**
+- Revoke access for lost or stolen devices
+- Temporarily disable suspicious devices
+- Enforce device trust requirements
+- Control device access to sensitive MCP servers
+
+### Data Protection
+
+**🛡️ Device Security**
+- Hardware fingerprinting prevents device spoofing
+- Encrypted device information storage
+- Secure device authentication
+- Protection against unauthorized device access
+
+**🔒 Privacy Controls**
+- Minimal device information collection
+- User control over device naming
+- Secure storage of device metadata
+- Clear data retention policies
+
+For platform-level device security details, see [Security and Privacy](/security#device-security).
+
+## Device Lifecycle Management
+
+### Device States
+
+**✅ Active Devices**
+- Recently used for MCP server access
+- Receiving configuration updates
+- Included in team analytics
+- Full access to team MCP installations
+
+**⏸️ Inactive Devices**
+- Not used recently (configurable threshold)
+- Configurations preserved but not updated
+- Excluded from active analytics
+- Can be reactivated by user login
+
+**🚫 Disabled Devices**
+- Manually disabled by administrators
+- No access to MCP servers
+- Configurations preserved for potential reactivation
+- Requires administrator action to re-enable
+
+**🗑️ Removed Devices**
+- Permanently removed from the system
+- All configurations deleted
+- Cannot be recovered
+- Audit trail preserved for compliance
+
+### Automatic Cleanup
+
+**⏰ Inactive Device Management**
+- Automatically mark devices inactive after configurable period
+- Send notifications before marking devices inactive
+- Preserve configurations for potential reactivation
+- Clean up truly abandoned devices
+
+**🧹 Data Retention**
+- Remove device data after extended inactivity
+- Preserve audit trails for compliance requirements
+- User notification before permanent deletion
+- Administrator override for important devices
+
+## Integration with MCP Configuration System
+
+Device management is deeply integrated with DeployStack's three-tier MCP configuration system:
+
+### Device-Specific User Configurations
+
+The user tier of the configuration system is inherently device-aware:
+
+- **Template Level**: Global admin defines what can be configured (device-independent)
+- **Team Level**: Team admin sets shared settings (inherited by all user devices)
+- **User Level**: Individual users configure personal settings **per device**
+
+For complete details on the three-tier system, see [MCP Configuration System](/mcp-configuration).
+
+### Configuration Assembly by Device
+
+When a user accesses MCP servers, configurations are assembled per device:
+
+```
+Final Configuration = Template + Team + User (This Device)
+
+Template (Global): Command, package, system flags
++ Team (Shared): API keys, shared directories, team standards
++ User Device (Personal): Device-specific paths, preferences, debug settings
+= Runtime Configuration for This Device
+```
+
+## Related Documentation
+
+For complete understanding of device management in context:
+
+- [MCP Configuration System](/mcp-configuration) - How device-specific configurations work within the three-tier system
+- [MCP User Configuration](/mcp-user-configuration) - User experience for multi-device configuration
+- [Security and Privacy](/security) - Platform-level device security implementation
+- [Gateway OAuth Implementation](/development/gateway/oauth) - Technical details of device registration during login
+- [Teams](/teams) - Team structure and device visibility for team administrators
+
+Device management enables DeployStack to provide secure, scalable, and user-friendly MCP server management across any number of devices while maintaining enterprise-grade governance and compliance capabilities.
\ No newline at end of file
diff --git a/docs/mcp-admin-schema-workflow.mdx b/docs/mcp-admin-schema-workflow.mdx
new file mode 100644
index 0000000..d60b1a5
--- /dev/null
+++ b/docs/mcp-admin-schema-workflow.mdx
@@ -0,0 +1,287 @@
+---
+title: MCP Schema Creation Workflow for Global Administrators
+description: Learn how global administrators transform raw MCP configurations into DeployStack's secure three-tier schema system with lock/unlock controls.
+sidebar: Admin Schema Workflow
+---
+
+# MCP Schema Creation Workflow for Global Administrators
+
+Global administrators transform raw MCP server configurations into structured schemas that enable teams and users to safely configure MCP servers. This workflow creates the foundation for DeployStack's three-tier configuration system.
+
+## Overview
+
+When you add new MCP servers to the catalog, you design the entire configuration experience by precisely categorizing every configuration element and setting sophisticated lock/unlock controls:
+- **What stays locked forever** (template elements like system commands, package names)
+- **What teams can configure and control** (team-level settings like API keys, shared credentials) 
+- **What users can always customize** (user-level settings like local paths, personal preferences)
+- **Lock/unlock defaults and visibility controls** for each configurable element
+
+For an overview of how the three-tier system works, see [MCP Configuration System](/mcp-configuration).
+
+## The Four-Step Admin Workflow
+
+Adding an MCP server to the catalog follows this process:
+
+```
+Step 1: GitHub Repository     ──→ Link to source repository
+Step 2: Claude Desktop Config ──→ Input raw configuration JSON  
+Step 3: Configuration Schema  ──→ **Categorize every element into three tiers with lock/unlock controls**
+Step 4: Basic Info           ──→ Set name, description, category
+```
+
+**Step 3** is the sophisticated categorization process where you transform raw configuration into the three-tier system with precise lock/unlock controls.
+
+### Step 1: GitHub Repository
+
+- **Repository URL** - GitHub repository containing the MCP server
+- **Branch** - Usually `main` or `master`
+- **Sync Settings** - Automatic vs manual synchronization
+
+### Step 2: Claude Desktop Configuration
+
+Input the raw Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/username/Desktop"
+      ]
+    }
+  }
+}
+```
+
+The system extracts all arguments and environment variables for categorization.
+
+### Step 3: Configuration Schema Definition
+
+Categorize every argument and environment variable from the Claude Desktop config into one of three tiers with sophisticated lock/unlock controls - this determines exactly what teams and users can configure.
+
+### Step 4: Basic Information
+
+- **Server Name** - Display name in catalog
+- **Description** - Clear explanation of functionality
+- **Category** - Organizational classification
+
+## Step 3: Configuration Schema Definition (Detailed)
+
+### The Sophisticated Categorization Process
+
+For every argument and environment variable extracted from the Claude Desktop config, you make precise categorization decisions with lock/unlock controls:
+
+**Categorization Options:**
+- **🔒 Template (Static)** - Locked forever, never changes (system commands, package names)
+- **🔧 Team Configurable** - Teams set values during installation and control user access
+- **🔓 User Configurable** - Always available for individual user customization
+
+**Lock/Unlock Controls:**
+- **Default Lock State** - Whether teams start with elements locked or unlocked for users
+- **Visibility Controls** - Whether users can see values (important for secrets)
+- **Schema Validation** - Data types, requirements, and constraints for each element
+
+This sophisticated system determines the exact configuration experience for teams and users.
+
+### Example: Filesystem MCP Server
+
+**Raw Configuration:**
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/username/Desktop"
+      ]
+    }
+  }
+}
+```
+
+**Your Categorization:**
+- **🔒 Template**: `-y` and `@modelcontextprotocol/server-filesystem` (system commands, locked forever)
+- **🔓 User Configurable**: `/Users/username/Desktop` (personal directory paths, default unlocked)
+- **No Team Level**: This server doesn't need shared team configuration
+
+**Lock/Unlock Decisions:**
+- Directory paths: Default unlocked (users can customize their own directories)
+- No visibility restrictions (directory paths are not sensitive)
+- Validation: Require valid directory paths, allow 1-10 directories per user
+
+**Result**: Users can configure their own directories, but can't modify the core system commands.
+
+### Another Example: API MCP Server with Secrets
+
+**Raw Configuration:**
+```json
+{
+  "mcpServers": {
+    "api": {
+      "command": "npx",
+      "args": ["-y", "@company/api-server"],
+      "env": {
+        "TEAM_API_KEY": "team-secret",
+        "DEBUG": "false"
+      }
+    }
+  }
+}
+```
+
+**Your Categorization:**
+- **🔒 Template**: System commands (`npx`, `-y`, package name) - locked forever
+- **🔧 Team Configurable**: `TEAM_API_KEY` (shared credential, team controls access)
+- **🔓 User Configurable**: `DEBUG` (personal preference, always available to users)
+
+**Lock/Unlock Decisions:**
+- `TEAM_API_KEY`: Default locked for users, hidden from users (security)
+- `DEBUG`: Default unlocked for users, visible to users (personal preference)
+- Validation: API key must be valid format, debug must be boolean
+
+**Result**: Teams manage shared API keys securely, users can toggle debug mode.
+
+### Smart Suggestions
+
+DeployStack provides suggestions to help with categorization:
+
+**🔒 Template Suggestions:**
+- CLI commands (`npx`, `python`, `node`)
+- Package names (`@modelcontextprotocol/server-*`)
+- System flags (`-y`, `--verbose`)
+
+**🔧 Team Configurable Suggestions:**
+- Variables containing "team", "api", "key"
+- Database connection strings
+- Service endpoints
+
+**🔓 User Configurable Suggestions:**
+- File paths with `/Users/` or `/home/`
+- Debug and preference settings
+- Device-specific configuration
+
+### Configuration Schema Step Interface
+
+The Configuration Schema Step presents a sophisticated interface for categorizing and controlling every configuration element:
+
+#### Arguments Categorization Interface
+```
+Extracted Arguments from Claude Desktop Config:
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ [0] "-y"                                                                   │
+│     Configuration Level: Template (Static) ▼                               │
+│     ✓ Locked Forever (Cannot be changed by teams or users)                │
+│                                                                             │
+│ [1] "@modelcontextprotocol/server-filesystem"                             │
+│     Configuration Level: Template (Static) ▼                               │
+│     ✓ Locked Forever (Cannot be changed by teams or users)                │
+│                                                                             │
+│ [2] "/Users/username/Desktop"                                              │
+│     Configuration Level: User Configurable ▼                               │
+│     ☐ Default Team Locked (Recommended: Unlocked for personal paths)       │
+│     Schema: Directory Path, Required: Yes, Min: 1, Max: 10                 │
+│                                                                             │
+│ [+] Add team-configurable argument                                          │
+│ [+] Add user-configurable argument                                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Environment Variables Categorization Interface
+```
+Extracted Environment Variables from Claude Desktop Config:
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ TEAM_TOKEN: "my-team-token"                                                 │
+│ Configuration Level: Team Configurable ▼                                   │
+│ ├─ Type: Secret ▼                                                          │
+│ ├─ Required: ✓                                                             │
+│ ├─ Description: Team authentication token                                   │
+│ ├─ ✓ Default Team Locked (Users cannot modify)                             │
+│ └─ ☐ Visible to Users (Recommended: Hidden for secrets)                  │
+│                                                                             │
+│ USER_TOKEN: "my-user-token"                                                 │
+│ Configuration Level: User Configurable ▼                                   │
+│ ├─ Type: Secret ▼                                                          │
+│ ├─ Required: ☐                                                             │
+│ ├─ Description: Personal user authentication token                          │
+│ └─ ☐ Default Team Locked (Recommended: Unlocked for user control)        │
+│                                                                             │
+│ [+] Add team-configurable environment variable                              │
+│ [+] Add user-configurable environment variable                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Lock/Unlock Control Matrix
+
+Your categorization decisions create a sophisticated control matrix across all three tiers:
+
+| Configuration Element | Global Admin Control | Team Admin Control | User Access |
+|-----------------------|---------------------|---------------------|-------------|
+| Template Args (Locked) | Define & Lock Forever | ❌ Cannot Change | ❌ Cannot Change |
+| Template Env (Locked) | Define & Lock Forever | ❌ Cannot Change | ❌ Cannot Change |
+| Team Args Schema | Define Schema & Defaults | Set Values & Lock/Unlock | Access if Unlocked |
+| Team Env Schema | Define Schema & Defaults | Set Values & Lock/Unlock | Access if Unlocked |
+| User Args Schema | Define Schema & Defaults | ✓ Always Available | ✓ Always Available |
+| User Env Schema | Define Schema & Defaults | ✓ Always Available | ✓ Always Available |
+| Additional Team Config | Define Limits | Add Custom Config | ❌ Cannot Change |
+| Additional User Config | Define Limits | ✓ Allow/Disallow | Add Personal Config |
+
+This matrix shows how your schema categorization creates precise boundaries for configuration control.
+
+## What Happens Next
+
+After you complete the sophisticated schema categorization:
+
+1. **Schema Generation** - System creates the complete three-tier schema structure with lock/unlock metadata
+2. **Catalog Addition** - MCP server is added to the global catalog with precise configuration boundaries
+3. **Team Access** - Teams can install and configure only the elements you designated as team-configurable
+4. **User Experience** - Users see only the elements you made available, with lock/unlock states controlled by teams
+
+Your categorization and lock/unlock decisions directly shape how teams and users interact with the MCP server across the entire three-tier system.
+
+## Security Validation
+
+The system automatically validates your sophisticated schema categorization:
+
+**Security Checks:**
+- ✅ Secrets properly categorized as team/user level with appropriate visibility controls
+- ✅ System commands locked at template level to prevent tampering
+- ⚠️ Warns if secrets might be visible inappropriately or unlocked by default
+- ✅ Validates lock inheritance logic across all three tiers
+
+**Schema Validation:**
+- ✅ All extracted elements are properly categorized
+- ✅ Required fields have appropriate defaults and validation rules
+- ✅ Lock/unlock inheritance makes logical sense across tiers
+- ✅ Data types and constraints are properly defined
+
+**Preview Capabilities:**
+- See exactly what team administrators will configure during installation
+- Preview what users will be able to customize based on team lock/unlock decisions
+- Understand the complete configuration flow from admin → team → user
+- Validate the security model with real-world scenarios
+
+## Key Benefits
+
+Your sophisticated schema categorization provides:
+
+**Security** - Sensitive data properly protected at the right tier with appropriate visibility controls
+**Precision** - Users see only what they can configure, teams control exactly what they need
+**Flexibility** - Teams can lock/unlock elements based on their specific organizational needs
+**Consistency** - Predictable configuration experience across all MCP servers in the catalog
+**Governance** - Complete audit trail and control over configuration inheritance across all tiers
+
+## Related Documentation
+
+For understanding how your sophisticated schemas are used across the three-tier system:
+
+- [MCP Configuration System](/mcp-configuration) - Overview of the three-tier system your schemas enable
+- [Team Installation](/mcp-team-installation) - How teams use your schemas to configure installations
+- [User Configuration](/mcp-user-configuration) - How users interact with the boundaries you define
+- [MCP Catalog](/mcp-catalog) - Where your categorized schemas are stored and managed
+
+The sophisticated schema creation workflow is the foundation that enables secure, flexible MCP server configuration with precise control over configuration inheritance across all teams and users.
diff --git a/docs/mcp-catalog.mdx b/docs/mcp-catalog.mdx
index 143df48..ade199b 100644
--- a/docs/mcp-catalog.mdx
+++ b/docs/mcp-catalog.mdx
@@ -134,7 +134,9 @@ Each server in the catalog includes comprehensive metadata:
 - **Tools**: Available MCP tools and their functions
 - **Resources**: Data sources and resource types
 - **Prompts**: Pre-configured prompts and templates
-- **Configuration**: Default settings and environment variables
+- **Configuration Schema**: Template definitions for team and user configuration options
+
+For details on how configuration schemas work in DeployStack's three-tier system, see [MCP Configuration System](/mcp-configuration).
 
 #### Repository Integration
 - **GitHub URL**: Source code repository
@@ -343,11 +345,13 @@ The catalog integrates seamlessly with DeployStack's deployment system:
 - **Update Notifications**: Alert users to security updates
 
 ### Data Protection
-- **Configuration Security**: Secure handling of server configurations
-- **Environment Variables**: Encrypted storage of sensitive settings
+- **Configuration Security**: Secure handling of server configurations and schemas
+- **Sensitive Data**: Encrypted storage through the three-tier configuration system
 - **Repository Access**: Secure GitHub integration
 - **Privacy Controls**: Respect team privacy and data boundaries
 
+For detailed security information about configuration handling, see [MCP Configuration System](/mcp-configuration).
+
 ## Future Enhancements
 
 ### Planned Features
diff --git a/docs/mcp-configuration.mdx b/docs/mcp-configuration.mdx
new file mode 100644
index 0000000..4d50df9
--- /dev/null
+++ b/docs/mcp-configuration.mdx
@@ -0,0 +1,199 @@
+---
+title: MCP Configuration System
+description: Understand DeployStack's three-tier configuration architecture that manages MCP server arguments, environment variables, and credentials with granular lock/unlock controls.
+sidebar: MCP Configuration
+---
+
+# MCP Configuration System
+
+DeployStack uses a three-tier configuration architecture to manage MCP server arguments, environment variables, and credentials. This system enables secure credential management, team collaboration, and individual customization through sophisticated lock/unlock controls.
+
+## Three-Tier Architecture Overview
+
+The system separates configuration into three distinct layers:
+
+1. **Template Level** - Global schemas and locked elements defined by administrators
+2. **Team Level** - Shared team configurations with lock/unlock controls  
+3. **User Level** - Personal configurations within team-defined boundaries **per device**
+
+This architecture enables teams to share common settings like API keys while allowing individual members to customize personal settings like local file paths across multiple devices. Each user can have different configurations on different devices while maintaining team security and standards.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ TIER 1: TEMPLATE (Global Admin)                                                │
+│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
+│ │ 🔒 Locked Elements: ["-y", "@modelcontextprotocol/server-filesystem"]     │ │
+│ │ 📋 Configuration Schemas: Define what teams/users can configure           │ │
+│ │ 🛡️ Lock/Unlock Rules: Set security boundaries                             │ │
+│ └─────────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ TIER 2: TEAM (Team Admin)                                                      │
+│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
+│ │ 🔧 Team Settings: API keys, shared credentials                             │ │
+│ │ 🔒/🔓 Lock Controls: Decide what users can customize                       │ │
+│ │ 👥 Team Isolation: Secure separation between teams                         │ │
+│ └─────────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ TIER 3: USER (Individual) - Device-Aware                                      │
+│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
+│ │ 🔓 Personal Settings: Local paths, preferences (per device)                │ │
+│ │ 💻 Multi-Device: Different configs per device with automatic registration   │ │
+│ │ 🔗 Automatic Inheritance: Use team credentials seamlessly across devices    │ │
+│ │ 🛡️ Device Security: Hardware fingerprinting and secure registration        │ │
+│ └─────────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│ RUNTIME: Final Configuration = Template + Team + User                          │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Lock/Unlock Control System
+
+The heart of the system is sophisticated lock/unlock controls with precise categorization:
+
+**Global Administrator Controls:**
+- **Sophisticated Categorization** - Categorize every configuration element into Template/Team/User tiers
+- **Granular Lock/Unlock Controls** - Set default lock states and visibility controls for each element
+- **Security Boundaries** - Define what can never be changed vs. what teams/users can configure
+- **Validation Rules** - Set data types, constraints, and security requirements for configurable elements
+- **Precise Schema Definition** - Create detailed schemas that control the exact configuration experience
+
+**Team Administrator Controls:**
+- **Configure Team Settings** - Set shared credentials and parameters within schema boundaries
+- **Control User Access** - Lock/unlock elements for team members based on organizational needs
+- **Manage Team Credentials** - Securely handle team-wide secrets with appropriate visibility controls
+- **Work Within Schema Boundaries** - Configure only elements designated as "Team Configurable" by global admins
+
+**User Access:**
+- **Personal Customization** - Modify only unlocked elements within boundaries set by global admin categorization
+- **Device-Specific Settings** - Configure personal settings across multiple devices with automatic device registration
+- **Secure Experience** - No access to locked configuration, team secrets, or template elements
+- **Focused Interface** - See only configuration elements designated as personally configurable
+- **Multi-Device Workflow** - Seamlessly work across different devices with device-specific configurations
+
+## User Journey Workflows
+
+Each tier has its own focused workflow:
+
+### For Global Administrators
+**[Admin Schema Workflow](/mcp-admin-schema-workflow)** - Learn how to transform raw MCP configurations into secure three-tier schemas with sophisticated lock/unlock controls through the Configuration Schema Step.
+
+Key workflow: Repository → Claude Desktop Config → **Configuration Schema Categorization** → Basic Info → Catalog Entry
+
+### For Team Administrators  
+**[Team Installation](/mcp-team-installation)** - Learn how to install MCP servers from the catalog, configure shared team settings, and control user access.
+
+Key workflow: Browse Catalog → Configure Team Settings → Set Lock Controls → Deploy Installation
+
+### For Individual Users
+**[User Configuration](/mcp-user-configuration)** - Learn how to configure personal MCP settings and customize your workflow across multiple devices.
+
+Key workflow: Access Team Installation → Configure Personal Settings → Multi-Device Setup → Save Configuration
+
+## Configuration Assembly Example
+
+Here's how the three tiers combine into a final runtime configuration:
+
+**Template (Global Admin):**
+```json
+{
+  "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+  "env": {"PROTOCOL_VERSION": "1.0"}
+}
+```
+
+**Team (Team Admin):**
+```json
+{
+  "args": [],
+  "env": {"SHARED_API_KEY": "team-secret-12345"}
+}
+```
+
+**User (Individual - i.e.: your MacBook Pro):**
+```json
+{
+  "args": ["/Users/alice/Development", "/Users/alice/Projects"],
+  "env": {"DEBUG": "true"}
+}
+```
+
+**Final Runtime Result:**
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y", 
+    "@modelcontextprotocol/server-filesystem",
+    "/Users/alice/Development", 
+    "/Users/alice/Projects"
+  ],
+  "env": {
+    "PROTOCOL_VERSION": "1.0",
+    "SHARED_API_KEY": "team-secret-12345", 
+    "DEBUG": "true"
+  }
+}
+```
+
+## Key Benefits
+
+**Security:** Sensitive credentials managed at appropriate tiers with encryption and access controls
+
+**Simplicity:** Users see only what they can configure, teams share common settings automatically
+
+**Flexibility:** Support for variable-length configurations and multi-device setups
+
+**Collaboration:** Teams coordinate through shared settings while maintaining individual customization
+
+**Governance:** Clear boundaries and audit trails for organizational compliance, with precise control over configuration inheritance
+
+## Common Use Cases
+
+**Development Teams:** Share Git tokens and project settings while allowing personal directory configurations
+
+**Data Science Teams:** Share database credentials and data lake access while supporting individual analysis workflows  
+
+**Support Teams:** Share customer service API keys while allowing personal workspace customization
+
+## Device-Aware Architecture Benefits
+
+**🏢 Enterprise Governance**
+- Complete visibility into device usage across the organization
+- Device-specific audit trails for compliance and security
+- Centralized device management with trust-based access control
+
+**👥 Team Collaboration**
+- Team administrators can see device usage patterns and optimize configurations
+- Device-specific insights help teams understand productivity patterns
+- Seamless collaboration across different device types and environments
+
+**🔒 Enhanced Security**
+- Hardware fingerprinting prevents device spoofing
+- Automatic device registration during secure OAuth2 login
+- Device trust management and access revocation capabilities
+- No separate device registration endpoints (security by design)
+
+For comprehensive device management details, see [Device Management](/device-management).
+
+## Related Documentation
+
+For complete system understanding:
+
+- [Device Management](/device-management) - Comprehensive device management and security
+- [MCP Catalog](/mcp-catalog) - Browse and discover available MCP servers
+- [Teams](/teams) - Team structure and membership management
+- [MCP Installation](/mcp-installation) - Basic MCP server installation concepts
+- [Security and Privacy](/security) - Platform security including device security
+
+The three-tier configuration system provides secure, scalable MCP server management that grows from individual developers to enterprise teams while maintaining simplicity and security at every level. Global administrators have sophisticated control over configuration boundaries through schema categorization, ensuring appropriate access and customization at each tier. The device-aware architecture enables seamless multi-device workflows while maintaining enterprise-grade security and governance.
diff --git a/docs/mcp-installation.mdx b/docs/mcp-installation.mdx
index e51f6ad..846a25c 100644
--- a/docs/mcp-installation.mdx
+++ b/docs/mcp-installation.mdx
@@ -1,12 +1,14 @@
 ---
 title: MCP Server Installation
-description: Learn how to install and manage MCP servers within your team workspace, including credentials, configuration, and team-scoped access.
+description: Learn how to install and manage MCP servers within your team workspace and understand the relationship between catalog, installations, and user configurations.
 sidebar: MCP Installation
 ---
 
 # MCP Server Installation
 
-MCP server installations are how your team actually uses MCP servers from the catalog. Think of the MCP catalog as a "store" where you browse available servers, and installations as the "purchased items" that your team can actually use with your own credentials and settings.
+MCP server installations are how your team actually uses MCP servers from the catalog. Think of the MCP catalog as a "store" where you browse available servers, and installations as the "purchased items" that your team can actually use with your own configurations.
+
+Installations represent the team layer in DeployStack's three-tier configuration system, where teams configure shared settings that all team members use. For complete details about how arguments, environment variables, and credentials work, see the [MCP Configuration System](/mcp-configuration) documentation.
 
 ## Understanding the Connection
 
@@ -38,22 +40,23 @@ graph TD
 **Every MCP server installation belongs to a specific team.** This is a fundamental principle of DeployStack:
 
 - **Team Ownership**: Each installation is owned by one team and isolated from other teams
-- **Team Credentials**: Your team provides and manages its own API keys, tokens, and configuration
-- **Team Configuration**: Customize server settings specific to your team's needs
+- **Team Configuration**: Teams manage the shared configuration layer that all team members inherit
 - **Team Privacy**: Other teams cannot see or access your installations
 
+For detailed information about how team configurations work within the three-tier system, see [MCP Configuration System](/mcp-configuration).
+
 ### Why Team-Scoped?
 
 This design provides several important benefits:
 
 #### Security Isolation
-- **Credential Separation**: Your team's API keys are completely separate from other teams
+- **Configuration Separation**: Your team's settings and credentials are completely separate from other teams
 - **Access Control**: Only your team members can use your team's installations
 - **Data Privacy**: No cross-team access to configurations or usage data
 
 #### Flexibility
 - **Custom Names**: Give installations meaningful names for your team context
-- **Team-Specific Settings**: Configure servers differently for your team's workflow
+- **Team-Specific Settings**: Configure shared team settings while allowing individual member customization
 - **Independent Updates**: Update or modify installations without affecting other teams
 
 #### Organization
@@ -69,15 +72,14 @@ Your team's MCP server installations are part of your complete team workspace:
 
 #### Team Resources
 - **MCP Installations**: Configured MCP servers ready to use
-- **Cloud Credentials**: Authentication for deployment platforms
-- **Environment Variables**: Global team settings
-- **Team Members**: Users who can access these resources
+- **Shared Configuration**: Team-level settings that all members inherit
+- **Team Members**: Users who can access these resources and create personal configurations
 
 #### Workspace Benefits
 - **Unified Management**: All team resources in one place
 - **Consistent Access**: Same permissions across all installations
-- **Shared Configuration**: Common settings available to all installations
-- **Team Collaboration**: All team members work with the same tools
+- **Configuration Hierarchy**: Team settings combined with personal user settings
+- **Team Collaboration**: All team members work with shared team configurations
 
 ### Database Storage
 
@@ -85,7 +87,7 @@ Behind the scenes, your team's installations are stored securely:
 
 #### Team-Level Storage
 - **Team Workspace**: All installations belong to your team's workspace
-- **Encrypted Credentials**: Your API keys and tokens are encrypted at rest
+- **Secure Configuration**: Team settings and credentials are encrypted at rest
 - **Access Control**: Only your team members can access the data
 - **Audit Trail**: Complete history of installation changes
 
@@ -102,8 +104,8 @@ Behind the scenes, your team's installations are stored securely:
 
 - **Your Environment**: Runs in your team's deployment environment
 - **Direct Control**: Full control over the server instance
-- **Custom Configuration**: Unlimited customization options
-- **Team Credentials**: Uses your team's API keys and authentication
+- **Flexible Configuration**: Team-level and user-level configuration options
+- **Secure Setup**: Uses DeployStack's three-tier configuration system
 
 ### Cloud Installations (Future)
 
@@ -112,26 +114,30 @@ Behind the scenes, your team's installations are stored securely:
 - **Managed Service**: DeployStack handles the infrastructure
 - **Simplified Setup**: Easier installation and maintenance
 - **Automatic Updates**: Managed updates and scaling
-- **Team Isolation**: Still team-scoped with your credentials
+- **Team Isolation**: Still team-scoped with the same configuration hierarchy
 
 ## Security Considerations
 
-### Credential Protection
+### Configuration Security
 
-Your team's installation credentials are protected through multiple layers:
+Your team's installation configurations are protected through multiple layers:
 
-- **Encryption at Rest**: All credentials are encrypted in the database
-- **Access Control**: Only team members can access credentials
-- **Secure Transmission**: Credentials are encrypted during transmission
-- **Audit Logging**: All credential access is logged for security
+- **Encryption at Rest**: All team configurations and credentials are encrypted in the database
+- **Access Control**: Only team members can access team configurations
+- **Secure Transmission**: All configuration data is encrypted during transmission
+- **Audit Logging**: All configuration access is logged for security
 
 ### Team Boundaries
 
 The team-scoped installation system provides strong security boundaries:
 
 - **Complete Isolation**: Teams cannot access each other's installations
-- **Separate Credentials**: Each team uses completely separate authentication
-- **Independent Configuration**: No shared configuration between teams
+- **Separate Configuration**: Each team uses completely separate settings and credentials
+- **Independent Setup**: No shared configuration between teams
 - **Secure Defaults**: Installations use secure default settings
 
-MCP server installations provide the bridge between the global catalog of available servers and your team's actual working environment. By understanding how installations work within your team workspace, you can effectively manage your team's MCP server landscape while maintaining security and organization.
+For comprehensive details about DeployStack's security model for configurations, see [MCP Configuration System](/mcp-configuration).
+
+MCP server installations provide the bridge between the global catalog of available servers and your team's actual working environment. They represent the team layer in DeployStack's three-tier configuration system, managing shared settings that all team members inherit while allowing individual customization.
+
+For complete understanding of how installations fit into the broader configuration architecture, see the [MCP Configuration System](/mcp-configuration) documentation.
diff --git a/docs/mcp-team-installation.mdx b/docs/mcp-team-installation.mdx
new file mode 100644
index 0000000..c43d963
--- /dev/null
+++ b/docs/mcp-team-installation.mdx
@@ -0,0 +1,157 @@
+---
+title: MCP Team Installation and Configuration
+description: Learn how team administrators configure MCP server installations, manage shared team settings, and control user access through lock/unlock controls.
+sidebar: Team Installation
+---
+
+# MCP Team Installation and Configuration
+
+Team administrators install MCP servers from the catalog and configure shared team settings that all team members inherit. You control what users can customize through lock/unlock settings.
+
+## Overview
+
+As a team administrator, you:
+
+- **Install MCP servers** from the catalog into your team workspace
+- **Configure shared settings** like API keys and common parameters
+- **Control user access** through lock/unlock settings
+- **Manage team credentials** securely for all team members
+
+For an overview of the three-tier system, see [MCP Configuration System](/mcp-configuration). For details on how global administrators create the schemas that define your configuration options, see [Admin Schema Workflow](/mcp-admin-schema-workflow).
+
+## Installation Process
+
+**The Installation Flow:**
+
+1. **Browse Catalog** - Find MCP servers in the global catalog
+2. **Select Server** - Choose a server that meets your team's needs
+3. **Configure Team Settings** - Set shared credentials and parameters
+4. **Set Lock Controls** - Decide what users can and cannot modify
+5. **Deploy Installation** - Make the server available to team members
+
+Each installation gets a meaningful name like "DevOps Team Filesystem" or "Customer Support Database" to help team members understand its purpose.
+
+The configuration options available to you are determined by how the global administrator categorized elements during schema creation. You can only configure elements that were designated as "Team Configurable" in the original schema definition.
+
+## Lock/Unlock Controls
+
+The lock/unlock system gives you granular control over what team members can modify, working within the boundaries established by global administrator schema categorization:
+
+**Your Control Scope:**
+- You can only configure elements categorized as "Team Configurable" by the global administrator
+- You can lock/unlock elements for team members (if the schema allows it)
+- You cannot modify "Template" elements (locked forever by global admin)
+- You cannot access "User Configurable" elements (managed by individual users)
+
+**Lock States:**
+- **🔒 Locked** - Users cannot modify this setting (team-controlled)
+- **🔓 Unlocked** - Users can customize this setting (user-controlled)
+
+**When to Lock:**
+- **Security** - API keys and sensitive credentials
+- **Standardization** - Settings that should be consistent across team
+- **Compliance** - Organizational policy requirements
+
+**When to Unlock:**
+- **Personal Workflow** - Individual customization needs
+- **Device Differences** - Different computers and environments
+- **User Preferences** - Personal productivity settings
+
+## Team Configuration Example
+
+**Development Team Filesystem Server:**
+
+```
+Installation Name: "Development Team Filesystem"
+
+Template Configuration (Set by Global Admin, Cannot Change):
+├─ Command: "npx" (🔒 Locked Forever)
+├─ Package: "@modelcontextprotocol/server-filesystem" (🔒 Locked Forever)
+├─ System Flag: "-y" (🔒 Locked Forever)
+
+Team Configuration (You Control):
+├─ GIT_ACCESS_TOKEN: "team-git-token-xyz" (🔒 Locked, Hidden)
+├─ SHARED_PROJECT_ROOT: "/company/projects" (🔒 Locked)
+
+User Controls (You Decide Lock/Unlock):
+├─ Personal Directories: 🔓 Unlocked (users add their own paths)
+├─ Debug Mode: 🔓 Unlocked (individual preference)
+```
+
+**Result:** Team members automatically inherit template configuration and team credentials, but can add personal directories and control debug settings within the boundaries you set.
+
+## Credential Management
+
+**Security Features:**
+- All team credentials are encrypted in the database
+- Team administrators can configure and modify credentials
+- Team members can use credentials but may not see actual values
+
+**Credential Visibility:**
+- **Hidden Credentials** - Users use them automatically but can't see values (for API keys)
+- **Visible Credentials** - Users can see values (for service URLs)
+
+**Updates:**
+- Update credentials without affecting user configurations
+- Changes automatically apply to all team members
+- No downtime during credential updates
+
+## Security and Isolation
+
+**Team Boundaries:**
+- Your team's installations are completely separate from other teams
+- No cross-team access to configurations or credentials
+- Only team administrators can modify team installations
+
+**Configuration Inheritance:**
+- Team settings automatically flow to all team members
+- Users build on top of team configuration
+- Clean separation between shared and personal settings
+
+## Device Visibility and Management
+
+As a team administrator, you have visibility into how team members use MCP servers across their devices:
+
+**📊 Team Device Overview**
+- See all devices used by team members
+- Monitor MCP server usage patterns by device
+- Identify device-specific configuration trends
+- Track team productivity across different device types
+
+**🔍 Device-Specific Insights**
+- Which MCP servers are used on which devices
+- How team members configure servers differently across devices
+- Device compliance with team policies
+- Usage analytics for optimization
+
+**🛡️ Security Management**
+- Monitor device access to team MCP installations
+- Identify unusual device activity patterns
+- Ensure device compliance with organizational policies
+- Support team members with device-related issues
+
+For comprehensive device management capabilities, see [Device Management](/device-management).
+
+## What Team Members Experience
+
+Based on your lock/unlock decisions and the schema boundaries set by global administrators, team members:
+
+- Only see configuration elements they can modify
+- Use team credentials automatically without seeing sensitive values
+- Can customize unlocked elements for their workflow across multiple devices
+- Get consistent behavior across all team members and devices
+- Benefit from automatic device registration and management
+
+For details on the user experience, see [MCP User Configuration](/mcp-user-configuration).
+
+## Related Documentation
+
+For complete understanding of team installations in context:
+
+- [MCP Configuration System](/mcp-configuration) - Overview of the three-tier system
+- [Admin Schema Workflow](/mcp-admin-schema-workflow) - How global administrators create the schemas that define your configuration options
+- [MCP User Configuration](/mcp-user-configuration) - How users interact with team installations
+- [Teams](/teams) - Team structure and management
+- [MCP Catalog](/mcp-catalog) - Browsing and selecting MCP servers
+
+Team installation is the critical bridge in DeployStack's three-tier configuration system, enabling secure shared resources while supporting individual team member productivity.
diff --git a/docs/mcp-user-configuration.mdx b/docs/mcp-user-configuration.mdx
new file mode 100644
index 0000000..d1985dc
--- /dev/null
+++ b/docs/mcp-user-configuration.mdx
@@ -0,0 +1,196 @@
+---
+title: MCP User Configuration and Personal Settings
+description: Learn how individual users configure personal MCP settings, customize their workflow across multiple devices, and work within team-defined boundaries.
+sidebar: User Configuration
+---
+
+# MCP User Configuration and Personal Settings
+
+Individual users customize personal MCP settings within boundaries set by their team administrators. You configure only the settings made available to you, focusing on personal productivity while automatically inheriting secure team credentials and standards.
+
+## Overview
+
+As a user, you personalize your MCP server experience within team-defined boundaries:
+
+- **Personal Settings** that adapt to your individual workflow
+- **Multi-Device Support** for different computers and environments  
+- **Automatic Team Integration** with shared credentials and team standards
+- **Simplified Interface** showing only settings you can modify
+- **Secure Experience** without credential management burden
+
+The user tier builds on team configurations, which build on global schemas. For an overview of the complete system, see [MCP Configuration System](/mcp-configuration).
+
+## Configuration Boundaries
+
+Your configuration options are precisely determined by how global administrators categorized elements during schema creation and your team administrator's lock/unlock decisions:
+
+**🔓 You Can Configure:**
+- **Unlocked Elements** - Settings your team admin made available for personal customization
+- **User-Specific Elements** - Settings designed for individual workflow (like local file paths)
+- **Device-Specific Settings** - Different configurations for different computers
+
+**🔒 You Cannot See or Modify:**
+- **Locked Team Settings** - Shared configuration controlled by team administrators
+- **Hidden Credentials** - API keys and secrets managed securely by your team
+- **Template Elements** - System-level parameters locked by global administrators
+
+**🔗 You Automatically Inherit:**
+- **Team Credentials** - API keys and authentication tokens
+- **Team Standards** - Shared settings and organizational preferences
+- **Template Configuration** - System-level parameters locked by global administrators
+
+For details on how global administrators define these boundaries and team administrators control access, see [Admin Schema Workflow](/mcp-admin-schema-workflow) and [Team Installation](/mcp-team-installation).
+
+## User Interface Experience
+
+When you configure an MCP server, you see a clean interface focused only on your personal options:
+
+```
+Personal Configuration: "Development Team Filesystem"
+
+YOUR PERSONAL SETTINGS
+
+Device: MacBook Pro ▼ [Change Device]
+
+Personal Directories (Add directories you want to access):
+├─ /Users/alice/Development
+├─ /Users/alice/Projects  
+└─ [+] Add another directory
+
+Debug Settings:
+├─ Enable Debug Mode: ✓
+└─ Debug Level: Verbose ▼
+
+TEAM-MANAGED SETTINGS (You inherit these automatically)
+
+✓ Team credentials configured
+✓ Shared project access: /company/projects
+✓ Team backup settings: Enabled
+
+[Save Configuration] [Test Configuration]
+```
+
+**Key Interface Features:**
+- **Only Personal Options** - You see only settings you can modify
+- **Clear Inheritance** - Understanding of what you get from your team
+- **Device Context** - Configure settings for specific devices
+- **Validation** - Immediate feedback on configuration validity
+
+## Multi-Device Support
+
+DeployStack supports different configurations for each device you use through automatic device registration and management:
+
+**Device Examples:**
+- **"MacBook Pro"** - Your personal laptop with development setup
+- **"Work Desktop"** - Office computer with different directory structure  
+- **"Cloud Workstation"** - Remote development environment
+
+**Adding a New Device:**
+1. **Automatic Detection** - System identifies this as a new device during login
+2. **Secure Registration** - Device is registered through OAuth2 authentication
+3. **Device Naming** - System uses hostname by default, you can customize
+4. **Configuration Setup** - Configure personal settings for this device
+5. **Team Inheritance** - Automatically inherit all team settings
+
+Each device maintains its own personal configuration while sharing team settings. Device registration happens automatically and securely - no manual setup required.
+
+**Device Security:**
+- Hardware fingerprinting ensures unique device identification
+- Device registration only happens during authenticated login
+- Administrators can manage device access for security
+
+For comprehensive device management details, see [Device Management](/device-management).
+
+## Personal Configuration Types
+
+### User Arguments
+
+Most commonly, you'll configure:
+
+**Directory Paths:**
+- Local directories you want MCP servers to access
+- Personal project folders
+- Document directories
+- Workspace locations
+
+**Example:**
+```
+Personal Directories:
+├─ /Users/alice/Development
+├─ /Users/alice/Projects
+└─ /Users/alice/Documents/Work
+```
+
+### User Environment Variables
+
+**Personal Preferences:**
+- Debug settings and logging levels
+- Interface customization options
+- Cache and temporary file locations
+
+**Device-Specific Settings:**
+- Local file paths and cache directories
+- Hardware-specific optimizations
+- Network and connection preferences
+
+## Configuration Process
+
+When you first configure an MCP server:
+
+1. **Access Team Installation** - Navigate to your team's MCP server installations
+2. **Select Server** - Choose the server you want to configure personally
+3. **Device Setup** - Provide a name for your current device
+4. **Personal Configuration** - Configure only the unlocked elements
+5. **Validation** - System validates your configuration against team schema
+6. **Save and Deploy** - Personal configuration is saved and ready to use
+
+## Configuration Assembly
+
+Your final MCP server configuration combines settings from all three tiers:
+
+```
+Final Configuration = Template + Team + Your Personal Settings
+
+Template (System):
+├─ Command: "npx"
+├─ Package: "@modelcontextprotocol/server-filesystem"
+└─ System flags: "-y"
+
++ Team (Shared):
+├─ Team API Key: "team-secret-12345" (hidden from you)
+├─ Shared directory: "/company/projects"
+└─ Backup enabled: true
+
++ Your Personal (Device):
+├─ Your directories: ["/Users/alice/Development", "/Users/alice/Projects"]
+├─ Debug: true
+└─ Log level: "verbose"
+
+= Final Runtime Configuration:
+Command: npx -y @modelcontextprotocol/server-filesystem 
+         /Users/alice/Development /Users/alice/Projects
+Environment: {
+  "TEAM_API_KEY": "team-secret-12345",
+  "SHARED_DIR": "/company/projects", 
+  "BACKUP_ENABLED": "true",
+  "DEBUG": "true",
+  "LOG_LEVEL": "verbose"
+}
+```
+
+**Automatic Validation:**
+- Your settings are validated against the schema
+- Type checking ensures correct data formats
+- Invalid directory paths are caught before saving
+- Missing required fields are highlighted
+
+## Related Documentation
+
+For complete understanding of user configuration in context:
+
+- [MCP Configuration System](/mcp-configuration) - Overview of the three-tier system
+- [Team Installation](/mcp-team-installation) - How team settings affect your options
+- [Admin Schema Workflow](/mcp-admin-schema-workflow) - How configuration boundaries are precisely defined through schema categorization
+- [Teams](/teams) - Team membership and structure
+
+User configuration represents the final personalization layer in DeployStack's three-tier system, enabling individual productivity while maintaining team security and organizational standards.
diff --git a/docs/security.mdx b/docs/security.mdx
index 1cd74c4..374d45e 100644
--- a/docs/security.mdx
+++ b/docs/security.mdx
@@ -59,6 +59,40 @@ All data is protected through:
 
 **What this means for you**: Your data is protected from common security attacks.
 
+## Device Security
+
+### Automatic Device Registration
+When you log into DeployStack from a new device:
+
+- **Secure Registration**: Device information is collected only during authenticated OAuth2 login
+- **Hardware Fingerprinting**: Each device gets a unique identifier based on system characteristics
+- **No Separate Endpoints**: Devices cannot be registered outside of the secure login process
+- **Automatic Detection**: System automatically identifies and registers your device
+
+**What this means for you**: Your devices are securely tracked without compromising your privacy or security.
+
+### Device Trust and Access Control
+DeployStack manages device access through trust-based security:
+
+- **Trusted Devices**: Devices you regularly use are automatically marked as trusted
+- **Access Control**: Administrators can revoke access for lost or stolen devices
+- **Device Monitoring**: Unusual device activity is detected and flagged
+- **Multi-Device Support**: Seamlessly work across laptops, desktops, and cloud workstations
+
+**What this means for you**: Your devices are protected, and you can work securely across multiple computers.
+
+### Device-Specific Configurations
+Your MCP server configurations are managed per device:
+
+- **Device Isolation**: Each device has its own personal configuration settings
+- **Shared Team Settings**: Team credentials and shared settings are inherited automatically
+- **Secure Storage**: Device-specific settings are encrypted and protected
+- **Configuration Sync**: Team settings update across all your devices automatically
+
+**What this means for you**: You can have different MCP configurations on different devices while maintaining team security.
+
+For comprehensive device management information, see [Device Management](/device-management).
+
 ## Account Access Control
 
 ### User Roles
diff --git a/docs/teams.mdx b/docs/teams.mdx
index 34d8846..6e22031 100644
--- a/docs/teams.mdx
+++ b/docs/teams.mdx
@@ -1,19 +1,19 @@
 ---
 title: Teams Structure in DeployStack
-description: Organize your MCP server management with teams - your workspace for managing servers, credentials, and environment variables in DeployStack.
+description: Organize your MCP server management with teams - your workspace for managing servers and configurations in DeployStack.
 sidebar: Teams
 ---
 
 # Teams
 
-Teams are the organizational foundation of DeployStack, serving as dedicated workspaces where you manage all your MCP server configurations, cloud provider credentials, and environment variables. Think of teams as isolated containers that keep your team resources organized and secure.
+Teams are the organizational foundation of DeployStack, serving as dedicated workspaces where you manage all your MCP server configurations and settings. Think of teams as isolated containers that keep your team resources organized and secure.
 
 ## Overview
 
 In DeployStack, teams provide:
 
 - **Isolated Workspaces**: Each team maintains its own separate environment for MCP server management
-- **Resource Organization**: All your MCP servers, credentials, and settings are organized within teams
+- **Resource Organization**: All your MCP servers and configurations are organized within teams
 - **Access Control**: Team-based permissions ensure secure access to your team resources
 - **Multi-Project Support**: Create multiple teams to organize different projects or environments
 - **Team Collaboration**: Teams support multiple members with role-based access control
@@ -51,16 +51,12 @@ Teams serve as comprehensive containers for all your team resources:
 - **Custom Configurations**: Team-specific server settings and parameters
 - **Process History**: Complete logs and monitoring data for team MCP servers
 
-### MCP Server Credentials
-- **API Keys and Tokens**: Secure storage for MCP server authentication
-- **Service Credentials**: Authentication tokens for various MCP server integrations
+### MCP Server Configuration
+- **Arguments and Environment Variables**: Teams manage the shared configuration layer in DeployStack's three-tier configuration system
+- **Credentials Management**: Secure storage and sharing of API keys and authentication tokens
+- **Team-Scoped Settings**: Configuration that applies to all team members
 
-### Global Environment Variables
-- **Node.js Environment Variables**: Custom env vars for Node.js-based MCP servers
-- **Reusable Variables**: Environment variables that can be applied across multiple servers
-- **Secure Storage**: All environment variables are encrypted and securely stored
-
-These global environment variables allow you to define common settings once and apply them to multiple MCP servers within the same team, streamlining your MCP server management.
+For complete details on how DeployStack handles arguments, environment variables, and credentials, see the [MCP Configuration System](/mcp-configuration) documentation.
 
 ## Team Management
 
@@ -232,10 +228,11 @@ These restrictions ensure that every user always has a personal, private team fo
 
 Each team maintains complete isolation:
 
-- **Separate Credentials**: MCP server credentials are team-specific
+- **Configuration Isolation**: All MCP server configurations are team-specific
 - **Independent Servers**: MCP servers in one team don't affect others
-- **Isolated Variables**: Environment variables are scoped to individual teams
-- **Secure Boundaries**: No cross-team access to resources
+- **Secure Boundaries**: No cross-team access to resources or credentials
+
+For detailed information about configuration isolation, see [MCP Configuration System](/mcp-configuration).
 
 ## Working with Teams
 
@@ -284,8 +281,7 @@ For each team, you can:
 
 - **Update Team Name**: Modify the display name
 - **Edit Description**: Change or add team descriptions
-- **Manage Credentials**: Add, update, or remove MCP server credentials
-- **Configure Variables**: Set up global environment variables
+- **Manage Configurations**: Configure team-level settings, credentials, and environment variables (see [MCP Configuration System](/mcp-configuration))
 - **Monitor MCP Servers**: View all MCP servers and their status
 
 ### Understanding Team Slugs
@@ -332,8 +328,7 @@ To delete a non-default team, you must:
 When you delete a team, you lose **everything** associated with it:
 
 - **All MCP Server Settings**: Complete server configurations and process history
-- **All MCP Server Credentials**: Stored API keys, tokens, and authentication data
-- **All Global Environment Variables**: Custom environment settings and variables
+- **All MCP Server Configurations**: Team-level settings, credentials, and environment variables
 - **Complete Process History**: Logs, monitoring data, and historical information
 
 ### No Recovery Options
@@ -369,8 +364,7 @@ Your team role affects your ability to:
 
 - Configure new MCP servers
 - Modify server configurations
-- Manage MCP server credentials
-- Set up environment variables
+- Manage team-level MCP server settings (see [MCP Configuration System](/mcp-configuration))
 - Monitor MCP server status
 - Access process logs
 
@@ -387,8 +381,7 @@ Consider creating separate teams for:
 Within each team:
 
 - **Group Related Servers**: Configure related MCP servers in the same team
-- **Shared Credentials**: Use the same MCP server credentials across servers
-- **Common Variables**: Leverage global environment variables for consistency
+- **Shared Configuration**: Use team-level credentials and settings across servers (see [MCP Configuration System](/mcp-configuration))
 - **Logical Organization**: Use descriptive names and descriptions
 
 Teams provide the foundation for organized, secure, and efficient MCP server management in DeployStack. By understanding how teams work, you can effectively manage your team resources and maintain clean separation between different projects and environments.