docs: Update database management and backend documentation; clarify OAuth server requirements and user credential management

Lasim · Lasim · commit 5f72e96dd953 · 2025-11-25T23:03:43.000+01:00
diff --git a/development/backend/database/index.mdx b/development/backend/database/index.mdx
@@ -498,7 +498,7 @@ turso db shell your-database
 
 The environment-based architecture makes it easy to add support for additional databases:
 
-- **PostgreSQL**: Planned for future release
+- **PostgreSQL**: Possible future addition
 - **MySQL**: Possible future addition
 - **Other SQLite-compatible databases**: Can be added with minimal changes
 
diff --git a/development/backend/index.mdx b/development/backend/index.mdx
@@ -13,7 +13,7 @@ The DeployStack backend is a modern, high-performance Node.js application built
 
 - **Framework**: Fastify for high-performance HTTP server
 - **Language**: TypeScript for type safety
-- **Database**: SQLite (default) or PostgreSQL with Drizzle ORM
+- **Database**: SQLite with Drizzle ORM
 - **Validation**: JSON Schema for request/response validation and OpenAPI generation
 - **Plugin System**: Extensible architecture with security isolation
 - **Authentication**: Dual authentication system - cookie-based sessions for frontend and OAuth 2.1 for satellite access
@@ -44,7 +44,7 @@ The development server starts at `http://localhost:3000` with API documentation
     href="/development/backend/database/index" 
     title="Database Management"
   >
-    SQLite and PostgreSQL setup, schema management, migrations, and Drizzle ORM best practices.
+    SQLite setup, schema management, migrations, and Drizzle ORM best practices.
   </Card>
   
   <Card 
@@ -162,7 +162,7 @@ services/backend/
 - **Type Safety**: Request/response validation with TypeScript
 
 ### Database Management
-- **Multi-Database Support**: SQLite (default) and PostgreSQL
+- **Multi-Database Support**: SQLite
 - **Type-Safe ORM**: Drizzle ORM with full TypeScript integration
 - **Migration System**: Automatic schema management
 - **Plugin Extensions**: Plugins can add their own tables
diff --git a/general/mcp-catalog.mdx b/general/mcp-catalog.mdx
@@ -142,6 +142,7 @@ Each server in the catalog includes comprehensive metadata:
 - **Tags**: Searchable keywords and labels
 - **Status**: Active, deprecated, or maintenance mode
 - **Sync Status**: Whether server is synced from official registry
+- **OAuth Requirement**: Whether server requires OAuth authorization (see [OAuth-Enabled MCP Servers](/mcp-oauth))
 
 #### Technical Specifications
 - **Language**: Programming language (TypeScript, Python, etc.)
diff --git a/general/mcp-configuration.mdx b/general/mcp-configuration.mdx
@@ -14,7 +14,9 @@ The system separates configuration into three distinct layers:
 2. **Team Level** - Shared team configurations with lock/unlock controls  
 3. **User Level** - Personal configurations within team-defined boundaries
 
-This architecture enables teams to share common settings like API keys while allowing individual members to customize personal settings like local file paths while maintaining team security and standards.
+This architecture enables teams to share common settings like API keys while allowing individual members to use their own private credentials or customize personal settings like local file paths - all within the same team installation, maintaining both team collaboration and individual privacy.
+
+**Note on OAuth-Enabled MCP Servers:** Some MCP servers require OAuth authorization, which happens at the user level—separate from this three-tier configuration system. Each user must authorize individually with their own account. For details, see [OAuth-Enabled MCP Servers](/mcp-oauth).
 
 ## How It Works
 
@@ -42,9 +44,9 @@ This architecture enables teams to share common settings like API keys while all
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │ TIER 3: USER (Individual)                                                      │
 │ ┌─────────────────────────────────────────────────────────────────────────────┐ │
-│ │ 🔓 Personal Settings: Local paths, preferences                             │ │
-│ │ 🔗 Automatic Inheritance: Use team credentials seamlessly                  │ │
-│ │ 🛡️ Team Security: Access controlled through team OAuth tokens             │ │
+│ │ 🔓 Personal Settings: Private credentials, local paths, preferences        │ │
+│ │ 🔗 Automatic Inheritance: Use team credentials OR your own private ones    │ │
+│ │ 🛡️ Privacy: Your credentials are NOT shared with other team members       │ │
 │ └─────────────────────────────────────────────────────────────────────────────┘ │
 └─────────────────────────────────────────────────────────────────────────────────┘
                                         │
@@ -67,17 +69,20 @@ The heart of the system is sophisticated lock/unlock controls with precise categ
 - **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:**
+**Team Administrator Controls (`team_admin` role only):**
+- **Install MCP Servers** - Only `team_admin` can install MCP servers to teams (not `team_user`)
 - **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
 
+**Important:** Users with `team_user` role cannot install MCP servers, view team credentials, or modify team settings. They can only configure their own personal user-level settings.
+
 **User Access:**
+- **Private Credentials** - Configure personal API keys and secrets that are NOT shared with other team members
 - **Personal Customization** - Modify only unlocked elements within boundaries set by global admin categorization
-- **Secure Experience** - No access to locked configuration, team secrets, or template elements
+- **Credential Privacy** - Your user-level credentials remain private and isolated from other team members
 - **Focused Interface** - See only configuration elements designated as personally configurable
-- **Team Integration** - Access through OAuth team authentication
 
 ## User Journey Workflows
 
@@ -88,16 +93,20 @@ Each tier has its own focused workflow:
 
 Key workflow: Repository → Claude Desktop Config → **Configuration Schema Categorization** → Basic Info → Catalog Entry
 
-### For Team Administrators  
+### For Team Administrators (`team_admin` role)
 **[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
+**Note:** Only users with `team_admin` role can perform team installations. Users with `team_user` role skip this step and go directly to user configuration.
+
+### For Individual Users (both `team_admin` and `team_user` roles)
 **[User Configuration](/mcp-user-configuration)** - Learn how to configure personal MCP settings and customize your workflow.
 
 Key workflow: Access Team Installation → Configure Personal Settings → Save Configuration
 
+**Note:** Both `team_admin` and `team_user` roles configure personal settings the same way. The difference is that only `team_admin` can install the MCP server to the team in the first place.
+
 ## Official Registry Configuration Mapping
 
 When MCP servers are synced from the official MCP Registry, their environment variables are automatically mapped to the appropriate tier based on their properties:
@@ -201,17 +210,21 @@ This automatic mapping enables synced servers from the official registry to work
 
 **Flexibility:** Support for variable-length configurations and individual customization
 
-**Collaboration:** Teams coordinate through shared settings while maintaining individual customization
+**Collaboration:** Teams coordinate through shared settings while maintaining individual customization and credential privacy
 
 **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
+**Development Teams:** Share org-wide Git tokens and project settings while team members can use their personal GitHub tokens for individual rate limits
+
+**Data Science Teams:** Share production database credentials at team level while data scientists use personal API keys for external services
+
+**Support Teams:** Share customer service API keys at team level while support agents use personal OAuth tokens for individual accountability
 
-**Data Science Teams:** Share database credentials and data lake access while supporting individual analysis workflows  
+**Rate Limit Management:** Team shares basic API access while individual users configure personal premium API keys for higher rate limits
 
-**Support Teams:** Share customer service API keys while allowing personal workspace customization
+**Multi-Account Access:** Team accesses shared resources while users maintain separate credentials for personal accounts or dev environments
 
 ## Official Registry Transport Types
 
diff --git a/general/mcp-oauth.mdx b/general/mcp-oauth.mdx
@@ -0,0 +1,252 @@
+---
+title: OAuth-Enabled MCP Servers
+description: Learn how to install and authorize OAuth-enabled MCP servers with per-user authentication and automatic token management.
+sidebarTitle: MCP OAuth Servers
+---
+
+Some MCP servers require OAuth authorization to access external services like Box, Google Drive, or Slack. OAuth-enabled servers work differently from standard MCP servers because each user must authorize individually with their own account.
+
+## Overview
+
+**OAuth-enabled MCP servers** connect to third-party services that require user consent. When your team installs an OAuth server, each team member must go through their own authorization flow.
+
+**Key Difference:**
+- **Standard MCP servers**: Team admin configures shared credentials
+- **OAuth MCP servers**: Each user authorizes with their personal account
+
+**Why User-Level Authorization?**
+- Alice's Google Drive ≠ Bob's Google Drive
+- Each user accesses their own data, not shared team data
+- OAuth tokens are private and encrypted per user
+- Actions are traceable to individual users for accountability
+
+**This is NOT:**
+- GitHub OAuth (used for logging into DeployStack)
+- Satellite OAuth (used for client connections)
+- Team-level configuration (args/env/headers from three-tier system)
+
+## How OAuth MCP Servers Work
+
+### Team Installation (Team Admin Only)
+
+When a `team_admin` installs an OAuth-enabled MCP server:
+
+1. **Browse the catalog** and find an OAuth server (Box, Google Drive, etc.)
+2. **Click "Install & Authorize"** to create the team installation
+3. **The team admin is redirected** to authorize with their own account
+4. **Installation appears in team** with "Connected" status for team admin
+
+**Important:** Only the team admin sees "Connected" at this point. Other team members will see "Auth Required" until they authorize.
+
+### Individual Authorization (All Users)
+
+When Bob (team_user) or any other team member views the installations:
+
+1. **Bob sees the installation** with "⚠ Auth Required" status
+2. **Bob clicks "Reconnect"** to start his own authorization
+3. **Browser popup opens** to the OAuth provider (Box, Google, etc.)
+4. **Bob consents** to DeployStack accessing his account
+5. **Bob is redirected back** and sees "✓ Connected" status
+
+**Result:** Bob's tokens are stored separately from Alice's tokens. Each user's MCP operations use their own credentials.
+
+## Authorization Flow
+
+### Step 1: User Initiates Authorization
+
+When you click "Authorize" or "Reconnect":
+- DeployStack starts OAuth discovery from the MCP server
+- A unique authorization URL is generated for you
+- PKCE security parameters are created (prevents token theft)
+
+### Step 2: Consent Screen
+
+A browser window opens showing:
+- The service you're authorizing (Box, Google, etc.)
+- What permissions DeployStack is requesting
+- Your personal account to authorize with
+
+**You choose:** Allow or Deny
+
+### Step 3: Token Exchange
+
+After you click "Allow":
+- The OAuth provider redirects you back to DeployStack
+- DeployStack exchanges the authorization code for tokens
+- Tokens are encrypted and stored with your user ID
+- You see "✓ Connected" status
+
+### Step 4: Automatic Token Management
+
+Once authorized:
+- Background job monitors token expiration
+- Tokens are automatically refreshed before they expire
+- You stay connected without re-authorizing
+- If refresh fails, you'll see "Auth Required" again
+
+## Multi-User Team Scenarios
+
+### Scenario: Three-Person Team with Box MCP
+
+**Team:** Acme Corp
+- Alice (team_admin)
+- Bob (team_user)
+- Carol (team_user)
+
+**Timeline:**
+
+1. **Alice installs Box MCP Server**
+   - Creates installation "Team Box Files"
+   - Alice authorizes with her Box account
+   - Alice sees: ✓ Connected
+
+2. **Bob logs in**
+   - Sees installation "Team Box Files"
+   - Status: ⚠ Auth Required
+   - Clicks "Reconnect"
+   - Authorizes with his Box account
+   - Bob sees: ✓ Connected
+
+3. **Carol logs in**
+   - Sees installation "Team Box Files"
+   - Status: ⚠ Auth Required
+   - Must authorize with her Box account
+   - Carol sees: ✓ Connected
+
+**Data Access:**
+- Alice's requests → Alice's Box files
+- Bob's requests → Bob's Box files
+- Carol's requests → Carol's Box files
+- No cross-user data access
+
+### Scenario: User Switches Teams
+
+**Context:** Alice is in both "Engineering Team" and "Marketing Team"
+
+**What Happens:**
+
+1. **Engineering Team** installs Google Drive MCP
+   - Alice authorizes with her Google account
+   - Alice's tokens stored for Engineering Team
+
+2. **Marketing Team** also has Google Drive MCP
+   - Alice must authorize again for Marketing Team
+   - Separate tokens stored for Marketing Team context
+   - Same Google account, different team = separate authorization
+
+**Why?** Tokens are stored per user + team + installation combination for security isolation.
+
+## Token Storage and Security
+
+### Encryption at Rest
+
+Your OAuth tokens are encrypted in the database using AES-256-GCM encryption:
+- Access tokens encrypted before storage
+- Refresh tokens encrypted before storage
+- Only decrypted when Satellite needs them at runtime
+
+For complete security details, see [Security and Privacy](/security).
+
+### Privacy Guarantees
+
+**Your tokens are private:**
+- Team admins cannot see your OAuth tokens
+- Other team members cannot see your OAuth tokens
+- Tokens are filtered by your user ID on every query
+
+**Your tokens are isolated:**
+- Each user has separate token records
+- Revoking your access doesn't affect other users
+- Your authorization status is independent
+
+### Runtime Token Injection
+
+When you use an OAuth MCP server:
+
+1. **Satellite receives your request** (with your user ID)
+2. **Satellite asks backend** for your tokens (filtered by user_id)
+3. **Backend decrypts** your tokens and returns them
+4. **Satellite injects tokens** into the MCP server process
+5. **MCP server uses your credentials** to access the service
+
+This happens automatically and transparently.
+
+## Token Refresh Process
+
+### Automatic Refresh
+
+A background job runs every few minutes:
+- Checks for tokens expiring soon (< 10 minutes remaining)
+- Uses the refresh_token to get new access_token
+- Updates stored tokens automatically
+- No user action required
+
+### When Refresh Fails
+
+If token refresh fails (revoked access, expired refresh token):
+- Your installation status changes to "⚠ Auth Required"
+- You see a prompt to re-authorize
+- Click "Reconnect" to start a new authorization flow
+- New tokens are stored after authorization
+
+## Identifying OAuth-Enabled Servers
+
+### In the MCP Catalog
+
+OAuth-enabled servers are marked with:
+- **"Requires OAuth" badge** in the server card
+- **OAuth indicator** in the server details
+- **Authorization notice** in the installation instructions
+
+### During Installation
+
+When installing an OAuth server:
+- Button text: "Install & Authorize" (not just "Install")
+- You'll be redirected to authorization immediately after installation
+- Installation won't be fully functional until authorized
+
+## Common Questions
+
+### Q: Can team admins authorize on behalf of users?
+
+**No.** Each user must authorize with their own account. Team admins cannot authorize for other users because OAuth tokens are tied to individual user accounts.
+
+### Q: What if I don't want to authorize?
+
+You won't be able to use that MCP server. The installation will show "Auth Required" and remain unusable until you authorize.
+
+### Q: Can I revoke access later?
+
+Yes. You can revoke DeployStack's access directly from the OAuth provider (Box, Google, etc.). DeployStack will show "Auth Required" status after revocation, and you can re-authorize anytime.
+
+### Q: Do I need to re-authorize if I leave and rejoin the team?
+
+Yes. When you leave a team, your tokens for that team are deleted. If you rejoin, you must authorize again.
+
+### Q: What happens if tokens expire while I'm using the server?
+
+The Satellite will detect expired tokens and return an error. You'll see "Auth Required" status and need to re-authorize.
+
+## Comparison with Other OAuth Types
+
+| Feature | GitHub OAuth | Satellite OAuth | MCP Server OAuth |
+|---------|-------------|-----------------|------------------|
+| **Purpose** | Login to DeployStack | Connect clients to Satellite | Access third-party services |
+| **Who authorizes** | Individual users | Team (via credentials) | Individual users |
+| **Frequency** | Once per login session | Per Satellite connection | Per MCP server |
+| **Storage** | Session cookies | Client configuration | Database (per-user) |
+| **Visibility** | User only | Team visible | User-private |
+| **Refresh** | Session-based | Client handles | Automatic background |
+| **Revocation** | Logout | Delete credentials | Revoke at provider |
+
+## Related Documentation
+
+For complete understanding of OAuth MCP servers in context:
+
+- [MCP Configuration System](/mcp-configuration) - Three-tier architecture (OAuth is separate)
+- [MCP Team Installation](/mcp-team-installation) - How team admins install OAuth servers
+- [MCP User Configuration](/mcp-user-configuration) - User settings and authorization
+- [MCP Catalog](/mcp-catalog) - Discovering OAuth-enabled servers
+- [Security and Privacy](/security) - Token encryption and storage security
+
+OAuth-enabled MCP servers provide secure, per-user access to external services while maintaining privacy and security through encrypted token storage and automatic token management.
diff --git a/general/mcp-team-installation.mdx b/general/mcp-team-installation.mdx
diff --git a/general/mcp-user-configuration.mdx b/general/mcp-user-configuration.mdx
