DeployStack Architecture Transition: From Gateway CLI to Satellite Infrastructure

DeployStack began as a local gateway solution for MCP (Model Context Protocol) management. After extensive development and team testing over several months, we identified fundamental architectural limitations that led us to deprecate the Gateway CLI approach and transition to a satellite-based infrastructure.

DeployStack Satellite

Gateway CLI Architecture (Deprecated)

What We Built

The Gateway CLI was a sophisticated local proxy solution with advanced technical features:

Core Components:

  • SSE (Server-Sent Events) + stdio dual transport architecture
  • Persistent MCP server process management with automatic restart
  • Team-aware configuration synchronization from cloud.deploystack.io
  • Cryptographic session management with secure credential injection
  • Advanced CLI interface with team switching capabilities

Technical Implementation:

  • Node.js/TypeScript application with global npm installation
  • HTTP server on localhost:9095 with SSE endpoints
  • JSON-RPC 2.0 communication over stdio with MCP subprocesses
  • Automatic tool discovery and caching system
  • Background process monitoring with health checks

Team Integration:

  • OAuth2 authentication with cloud.deploystack.io
  • Team-specific MCP server configurations
  • Role-based access control (global_admin, global_user, team_admin, team_user)
  • Centralized credential management with runtime injection

Gateway Limitations Discovered

Installation Complexity: Local installation required multiple steps: npm global install, authentication, VS Code configuration, and local process management. Each step introduced potential failure points.

Process Management Issues: Managing persistent background processes created system resource conflicts, port management complexity, and cross-platform compatibility problems.

Corporate Network Challenges: Outbound connections to cloud.deploystack.io for configuration sync occasionally failed behind restrictive corporate firewalls.

Development Overhead: Maintaining cross-platform compatibility, handling process lifecycle management, and debugging local networking issues consumed significant development resources.

Satellite Architecture (Current)

Design Principles

Edge Worker Pattern: Satellites operate as intelligent edge workers that handle MCP server execution while maintaining centralized configuration management through cloud.deploystack.io.

Dual Deployment Model:

  • Global Satellites: DeployStack-operated infrastructure serving all teams
  • Team Satellites: Customer-deployed within corporate networks for internal resource access

Standard Protocol Integration: Satellites expose standard MCP interfaces via HTTPS endpoints, eliminating custom client requirements.

Technical Architecture

Core Components:

  1. HTTP Proxy Router: Team-aware request routing with protocol translation
  2. Process Manager: MCP server subprocess lifecycle with resource isolation
  3. stdio Communication Manager: JSON-RPC communication with MCP processes
  4. Backend Communicator: Integration with cloud.deploystack.io control plane
  5. OAuth 2.1 Resource Server: Authentication and authorization for MCP clients

Resource Management:

  • Linux namespaces and cgroups v2 for complete team isolation
  • Resource jailing: 0.1 CPU cores, 100MB RAM per team
  • 5-minute idle timeout for inactive MCP server processes
  • Process-level user isolation with dedicated system accounts

Implementation Stack:

  • Fastify HTTP server with @fastify/http-proxy for request routing
  • stdio JSON-RPC communication with MCP server subprocesses
  • Docker containerization with team-specific resource limits
  • OAuth 2.1 compliance for enterprise authentication

Client Integration

MCP Client Configuration:

{
  "mcpServers": {
    "deploystack": {
      "url": "https://satellite.deploystack.io/mcp",
      "transport": "http"
    }
  }
}

Authentication Flow:

  1. User authenticates with cloud.deploystack.io
  2. Client receives OAuth2 access token
  3. Token validates against satellite OAuth 2.1 resource server
  4. Satellite routes requests based on team context

Migration Details

Deprecated Components

Gateway CLI Application:

  • Command-line interface (deploystack login, deploystack start, etc.)
  • Local HTTP server with SSE endpoints
  • npm package distribution and versioning
  • Cross-platform installation procedures

Supporting Infrastructure:

  • Local process management and monitoring
  • localhost configuration requirements
  • Platform-specific installation documentation

Current Infrastructure

Global Satellite Network:

  • Multi-region deployment for low-latency access
  • Auto-scaling infrastructure managed by DeployStack team
  • High availability with 99.9% uptime target
  • Standard HTTPS endpoints accessible from any network

Team Satellite Support:

  • Docker-based deployment for customer networks
  • Outbound-only communication pattern (firewall-friendly)
  • Complete team isolation with dedicated resources
  • Integration with internal corporate infrastructure

Technical Benefits

Simplified Client Experience

Before (Gateway CLI):

  • Multi-step installation: npm install, login, configuration
  • Local process management and port conflicts
  • Platform-specific troubleshooting and support

After (Satellite):

  • Single URL configuration in MCP client
  • No local software installation or management
  • Standard HTTPS communication patterns

Enhanced Security Model

Team Isolation:

  • Complete process isolation using Linux namespaces
  • Dedicated system users per team with file system boundaries
  • Network isolation preventing cross-team communication
  • Resource quotas preventing denial-of-service scenarios

Enterprise Authentication:

  • OAuth 2.1 compliance for enterprise SSO integration
  • Token-based authentication eliminating credential storage
  • Centralized access control through cloud.deploystack.io
  • Comprehensive audit logging for compliance requirements

Operational Improvements

Infrastructure Management:

  • Centralized monitoring and alerting
  • Automated scaling based on demand
  • Zero-downtime deployments and updates
  • Professional monitoring and incident response

Developer Experience:

  • Instant access without installation delays
  • Consistent behavior across all environments
  • No local system dependencies or conflicts
  • Transparent operation with debugging support
  • Breaking Changes

Gateway CLI Removal

All Gateway CLI functionality has been removed. Users must migrate to satellite-based access:

  1. Uninstall global gateway package: npm uninstall -g @deploystack/gateway
  2. Update MCP client configuration to use satellite URLs
  3. Authenticate through cloud.deploystack.io web interface

Future Development

Planned Enhancements

Enhanced Team Satellites:

  • Advanced resource management and scaling
  • Integration with enterprise identity providers
  • Custom MCP server deployment and management

Global Satellite Expansion:

  • Additional regions for improved latency
  • Enhanced monitoring and observability
  • Advanced caching and performance optimization

Open Source Development

The complete satellite architecture remains open source with active community development. Contributions welcome for both global and team satellite implementations.

Conclusion

The transition from Gateway CLI to Satellite architecture represents a fundamental improvement in DeployStack's approach to MCP management. By eliminating local installation complexity while maintaining enterprise-grade security and team isolation, the satellite model provides a superior foundation for both individual developers and enterprise teams.

The technical architecture supports the full spectrum of deployment scenarios while significantly reducing operational complexity for end users. This architectural foundation positions DeployStack for continued growth and enterprise adoption in the expanding MCP ecosystem.

Share: