Team Context in Gateway CLI

The DeployStack Gateway CLI is fundamentally team-centric. All MCP server installations and operations are scoped to the currently selected team, reflecting the architectural design where teams serve as isolated workspaces for deployment resources.

Team Selection Architecture

Secure Storage Location

Team selection is stored securely alongside authentication credentials using:

Primary: OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Fallback: Encrypted file at ~/.deploystack/credentials.enc

The selected team information is part of the StoredCredentials interface:

interface StoredCredentials {
  // ... other credential fields
  selectedTeam?: {
    id: string;    // Team ID for API operations
    name: string;  // Team name for display
  };
}

Automatic Default Selection

When users authenticate via deploystack login, the CLI automatically:

Fetches user's teams from /api/teams/me
Identifies the default team (is_default: true)
Sets it as the selected team in secure storage
Confirms selection to the user

Team Switching

Users can change their active team context using:

deploystack teams --switch <team-name>

This updates the stored team selection, affecting all subsequent CLI operations.

MCP Server Installation Scope

Database Architecture

MCP server installations are stored in the mcpServerInstallations table with team-based foreign keys:

mcpServerInstallations:
  - team_id (FK to teams.id)        -- Scopes installation to specific team
  - server_id (FK to mcpServers.id) -- References the MCP server definition
  - user_environment_variables      -- Team-specific encrypted credentials

Team-Scoped Operations

All MCP-related CLI operations operate within the selected team context:

Credential Injection: Environment variables are team-specific
Server Availability: Only team's installed servers are accessible
Configuration Sync: Gateway downloads only selected team's configurations
Process Management: Spawned MCP processes use team-scoped credentials

MCP Configuration Management: For detailed information about how the Gateway downloads, processes, and stores MCP server configurations from the backend API, see the Gateway MCP Configuration documentation.

Cross-Team Isolation

The architecture ensures complete isolation between teams:

Team A cannot access Team B's MCP server installations
Credentials are encrypted per team context
No cross-team data leakage in local processes

CLI Implementation Details

Storage Methods

The CredentialStorage class provides team selection methods:

updateSelectedTeam(teamId, teamName) - Updates selected team
getSelectedTeam() - Retrieves current selection
Team data is persisted with other authentication credentials

Team-Aware Commands

Key commands that depend on team context:

deploystack start - Starts gateway for selected team's MCP servers
deploystack teams - Shows selection status and switching options
Future MCP management commands will operate on selected team

API Integration

Team context affects backend communication:

All MCP-related API calls include team context
Configuration sync requests are team-scoped
Credential retrieval is filtered by team membership

Developer Guidelines

Working with Team Context

When developing CLI features that interact with MCP servers:

Always check team selection before MCP operations
Use team ID for API calls (not just team name)
Scope local storage by team when caching configurations
Validate team access before exposing functionality

Future Considerations

The team context system is designed to support:

Multi-team development workflows
Team-specific MCP server catalogs
Role-based access to different tool sets
Enterprise governance and audit trails

For complete team management information, see the Teams documentation.

Error Handling

CLI commands should gracefully handle team context issues:

No team selected: Prompt user to select a team
Invalid team: Guide user to available teams
Team access revoked: Require re-authentication
Team deleted: Clear selection and prompt for new team

This team-centric design ensures that the Gateway CLI operates as a secure, isolated workspace aligned with organizational boundaries while maintaining a smooth developer experience.

On this page