Skip to content

index.mdx

Latest commit

 

History

History
217 lines (170 loc) · 7.49 KB

index.mdx

File metadata and controls

217 lines (170 loc) · 7.49 KB
Raw
title Gateway Development
description Developer documentation for the DeployStack Gateway - the local secure proxy that manages MCP servers and credentials for enterprise teams.
sidebar Gateway
icon Terminal

import { Card, Cards } from 'fumadocs-ui/components/card'; import { Terminal, Code2, Settings, Shield, Zap, Users, Rocket } from 'lucide-react';

DeployStack Gateway Development

The DeployStack Gateway is the local secure proxy that connects developers to their team's MCP servers through a centralized control plane. It acts as a smart process manager and credential vault, running MCP server processes as persistent background services while enforcing access policies from the cloud.

Architecture Overview

The Gateway implements a sophisticated Control Plane / Data Plane architecture with comprehensive transport support:

  • Control Plane: Authenticates with cloud.deploystack.io to download team configurations and access policies
  • Data Plane: Manages local MCP server processes with stdio, SSE, and Streamable HTTP transport protocols
  • Security Layer: Injects credentials securely into process environments without exposing them to developers
  • Session Management: Handles secure SSE connections with cryptographic session IDs for VS Code compatibility
  • Transport Layer: Supports both legacy SSE transport and modern Streamable HTTP transport for maximum client compatibility

Core Features

} title="Triple Transport Support" > Supports stdio transport for CLI tools, SSE transport for VS Code compatibility, and Streamable HTTP for modern MCP clients

<Card icon={} title="Secure Credential Injection"

Injects API tokens and credentials directly into process environments without developer exposure

<Card icon={} title="Individual Tool Exposure"

Exposes individual MCP tools with namespacing (e.g., brightdata-search_engine) for direct use in development environments

<Card icon={} title="Session Management"

Cryptographically secure session handling with automatic cleanup for persistent connections

<Card icon={} title="Unified Proxy"

Single HTTP endpoint supporting multiple client types with intelligent request routing

<Card icon={} title="Team-Based Access"

Enforces team-based access control policies downloaded from the cloud control plane

<Card icon={} title="Tool Caching System"

Team-aware caching enables instant gateway startup and automatic tool discovery on team switching

Development Setup

Prerequisites

  • Node.js (v18 or higher)
  • npm (v8 or higher)
  • TypeScript development environment
  • A DeployStack account at cloud.deploystack.io

Local Development

# Navigate to the gateway service
cd services/gateway

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Start production build
npm start

Key Components

Authentication Module

Handles secure authentication with the DeployStack cloud control plane and manages access tokens.

Configuration Sync

Downloads and synchronizes team MCP server configurations, including process spawn commands and environment variables.

Process Manager

Manages the lifecycle of MCP server processes, including:

  • On-demand process spawning
  • Stdio communication handling
  • Process cleanup and resource management
  • Environment variable injection

HTTP Proxy Server

Exposes multiple endpoints for different client types:

  • GET /sse: SSE connection establishment for VS Code and legacy clients
  • POST /message: Session-based JSON-RPC for SSE clients
  • POST /mcp: Streamable HTTP endpoint for modern MCP clients
  • GET /health: Health check endpoint for monitoring

Session Manager

Handles secure SSE connections with:

  • Cryptographically secure session ID generation
  • Session lifecycle management and cleanup
  • Connection state tracking and validation
  • Automatic timeout and resource management

Enterprise Management Layer

Transforms MCP servers into enterprise governance tools:

  • Each MCP server appears as a toggleable tool
  • Enable/disable/status actions for operational control
  • Rich metadata from secure catalog integration
  • Team-based access policy enforcement

Security Layer

Ensures credentials are handled securely:

  • Encrypted storage of downloaded configurations
  • Secure environment variable injection
  • No credential exposure to developer environment
  • Session-based authentication for persistent connections

Configuration Format

The Gateway works with MCP server configurations in this format:

{
  "name": "brightdata",
  "command": "npx",
  "args": ["@brightdata/mcp"],
  "env": {
    "API_TOKEN": "secure-token-from-vault"
  }
}

Development Workflow

  1. Authentication: Gateway authenticates with cloud control plane
  2. Config Download: Downloads team's MCP server configurations
  3. Persistent Process Startup: Starts all configured MCP servers as background processes when gateway launches
  4. HTTP Server: Starts local HTTP server with multiple endpoints immediately available:
    • SSE endpoint: localhost:9095/sse (for VS Code and legacy clients)
    • Messages endpoint: localhost:9095/message (for session-based JSON-RPC)
    • MCP endpoint: localhost:9095/mcp (for modern Streamable HTTP clients)
    • Health endpoint: localhost:9095/health (for monitoring)
  5. Request Handling: Receives MCP requests from development tools and intelligently routes to appropriate transport
  6. Process Management: Maintains persistent background processes as described in Gateway Process Management.
  7. Credential Injection: Securely injects environment variables into running processes at startup
  8. Tool Routing: Routes namespaced tool calls to persistent MCP servers via stdio transport
  9. Transport Selection: Automatically detects client capabilities and uses appropriate transport (SSE or Streamable HTTP)

For detailed information about the caching system, see Gateway Caching System.

Language Support

The Gateway is language-agnostic and supports MCP servers written in:

  • Node.js: npx, node commands
  • Python: python, pip, pipenv commands
  • Go: Compiled binary execution
  • Rust: Compiled binary execution
  • Any Language: Via appropriate runtime commands

Security Considerations

Credential Management

  • Credentials are never written to disk in plain text
  • Environment variables are injected directly into spawned processes
  • No credential exposure to the developer's shell environment

Process Isolation

  • Each MCP server runs in its own isolated process
  • Process cleanup ensures no resource leaks
  • Automatic process termination after idle periods

Network Security

  • Local HTTP server only binds to localhost
  • No external network exposure by default
  • Secure communication with cloud control plane

Contributing

The Gateway is actively under development. Key areas for contribution:

  • Process Management: Improving spawn/cleanup logic
  • Security: Enhancing credential handling
  • Performance: Optimizing stdio communication
  • Platform Support: Adding Windows/Linux compatibility
  • Error Handling: Robust error recovery