Gateway MCP Configuration Management

The DeployStack Gateway CLI automatically manages MCP (Model Context Protocol) server configurations for teams, downloading installation data from the backend API and storing it securely for local process management.

Overview

The Gateway implements a sophisticated MCP configuration system that:

Downloads team MCP installations from the backend API
Processes raw API data into Gateway-ready server configurations
Stores both raw and processed data securely using OS-level storage
Manages team context switching with automatic config updates

API Integration

Endpoint

The Gateway fetches MCP installations from:

GET /api/teams/{teamId}/mcp/installations

Response Structure

The API returns team MCP installations with this interface:

interface MCPInstallationsResponse {
  success: boolean;
  data: MCPInstallation[];
}

Data Storage Architecture

Dual Storage Approach

The Gateway stores both raw API data and processed configurations:

Raw Installations - Complete API response for audit and debugging
Processed Server Configs - Gateway-ready configurations for process spawning

Storage Interface

interface TeamMCPConfig {
  team_id: string;
  team_name: string;
  installations: MCPInstallation[];  // Raw API data
  servers: MCPServerConfig[];        // Processed configs
  last_updated: string;
}

Secure Storage

Primary: OS Keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Fallback: AES-256-CBC encrypted files
Key Format: ${userEmail}-${teamId} for team isolation

Configuration Processing

The Gateway transforms raw API installations into executable server configurations:

Runtime Detection

Node.js: npx @package-name
Python: python -m package_name
Go: Direct binary execution
Custom: Uses installation_methods from API

Environment Variable Merging

Server default environment variables
User-customized overrides from user_environment_variables
Secure injection at process spawn time

Team Context Integration

Automatic Management

Login: Downloads default team's MCP configuration
Team Switch: Clears old config, downloads new team's config
Logout: Clears all stored MCP configurations

Configuration Lifecycle

API authentication and team selection
MCP installations download via API
Data validation and filtering
Configuration processing and transformation
Secure storage with team isolation
Runtime access for process management

Developer Commands

Configuration Management

deploystack mcp --status - Show current configuration status
deploystack mcp --refresh - Force refresh from API
deploystack mcp --clear - Clear stored configuration
deploystack mcp --test - Run processing validation tests

Debug Information

The deploystack mcp command shows raw stored data including:

Complete team information
Processed server configurations
Raw API installation data
Environment variables (with sensitive data masking)

Security Considerations

Data Isolation

Each team's configuration stored with unique keys
No cross-team data access possible
Automatic cleanup on team changes

Credential Protection

Environment variables injected at runtime only
No plain text storage of sensitive data
OS-level keychain integration for maximum security

Tool Discovery and Caching

Beyond configuration management, the Gateway implements an advanced tool discovery system that automatically identifies and caches individual tools from each MCP server. This system operates seamlessly with the configuration management to provide:

Automatic Discovery

Team Switching: Tools are automatically discovered from all servers when switching teams
Configuration Updates: Tool cache is refreshed when server configurations change
Manual Refresh: Developers can explicitly refresh tools using CLI commands

Team-Aware Caching

Isolated Storage: Each team's discovered tools are cached separately
Fast Startup: Gateway starts instantly using cached tool information
Fallback Support: Cached tools remain available even when servers are temporarily unavailable

For comprehensive details about the tool discovery and caching system, see Gateway Caching System.

Developer Commands

Configuration Management

deploystack mcp --status - Show current configuration status
deploystack mcp --refresh - Force refresh from API
deploystack mcp --clear - Clear stored configuration

Tool Discovery

deploystack mcp --tools <server-number> - Discover and display tools from a specific MCP server (requires running gateway)
deploystack teams --switch <team-number> - Switch teams with automatic tool discovery

Note: The --tools command only works when the gateway is running (deploystack start), as it communicates with already-running MCP server processes rather than spawning them on-demand.

Integration Points

The stored MCP configurations are consumed by:

Process Manager - Spawns MCP server processes using stored configs as described in Process Management
HTTP Proxy - Routes requests to appropriate MCP servers using cached tool information
Environment Injection - Securely provides credentials to spawned processes
Tool Discovery System - Uses configurations to discover and cache available tools as detailed in Gateway Caching System

This system ensures that the Gateway has immediate access to team-specific MCP server configurations while maintaining security and team isolation throughout the development workflow.

On this page