DeployStack Gateway

The local secure gateway that connects developers to their team's MCP servers through a centralized control plane. The DeployStack Gateway acts as a smart proxy, managing MCP server processes locally while enforcing access policies from the cloud.

🔍 Features

- Dual Transport Architecture: Supports both legacy SSE transport and modern Streamable HTTP transport for maximum MCP client compatibility
- Individual Tool Exposure: Exposes individual MCP tools with namespacing (e.g., brightdata-search_engine) for direct use
- Automatic Tool Discovery: Discovers and caches tools from all MCP servers when switching teams
- Fast Gateway Startup: Instant startup using cached tools without waiting for server discovery
- Process Management: Runs MCP server processes as persistent background services for instant tool availability
- Secure Credential Injection: Injects credentials directly into MCP server processes without exposing them to developers
- Modern SSE Endpoints: Clean /sse endpoint for connections and /message for session-based communication
- Team-Based Access Control: Only exposes MCP servers that your team has access to
- Team-Aware Caching: Each team's tools are cached separately with complete isolation
- Language Agnostic: Supports MCP servers written in Node.js, Python, Go, Rust, and more
- Automatic Update Checking: Built-in npm version checking with smart update notifications

🛠️ Installation

``bash

`Installation command coming soon`


npm install -g @deploystack/gateway


🚀 Usage

`bash

`Login to your DeployStack account (automatically starts the gateway)`


deploystack login
Check status

deploystack status
Or start the gateway manually if needed

deploystack start


🧱 How It Works

1. Login & Auto-Start: The gateway authenticates with cloud.deploystack.io, downloads your team's MCP server configurations, and automatically starts the gateway server 2. Persistent Process Startup: All configured MCP servers launch as persistent background processes immediately after login 3. Tool Discovery: Automatically discovers and caches individual tools from all running MCP servers for your team 4. SSE Connection: VS Code connects to/sseendpoint and receives session information for message routing 5. Session-Based Communication: All JSON-RPC requests are sent to/messageendpoint with session context 6. Instant Tool Access: All MCP tools are instantly available since servers run continuously in the background 7. Credential Injection: Securely injects API tokens and credentials into MCP server process environments at startup 8. Tool Routing: Routes namespaced tool calls (e.g.,brightdata-search_engine) to already-running MCP servers via stdio

`📋 Prerequisites`

- Node.js (v18 or higher) - npm (v8 or higher) - A DeployStack account at cloud.deploystack.io

`🏗️ Architecture`

`$3`

The DeployStack Gateway implements a modern dual-endpoint SSE architecture for VS Code compatibility:

`text 1. Client connects: GET /sse 2. Gateway responds: SSE stream + session endpoint 3. Client sends: POST /message?session=xyz (JSON-RPC) 4. Gateway responds: Via SSE stream (real-time)`

Connection Flow:

1. SSE Connection: VS Code connects to GET /sse2. Session Creation: Gateway creates secure session and returns endpoint via SSE 3. Message Routing: Client sends JSON-RPC toPOST /message?session=xyz4. Response Streaming: Gateway responds via the SSE connection

Benefits:

- ✅ VS Code Compatible: Follows exact SSE pattern VS Code expects - ✅ Real-time Communication: Persistent connections enable instant responses - ✅ Session Security: Cryptographically secure session management - ✅ Modern Architecture: Clean separation between connection and messaging

`$3`

The gateway runs MCP servers as persistent background processes:

- Startup: All team MCP servers launch when gateway starts - Always Ready: Tools available instantly (no spawn delays) - Secure Environment: Credentials injected at process startup - Team Isolation: Each team's processes run separately - Graceful Lifecycle: Proper MCP protocol initialization and cleanup

`🔧 Configuration`

After logging in, the gateway automatically downloads and synchronizes your team's configuration. No manual configuration required!

VS Code/Cursor Configuration:

`json { "mcpServers": { "deploystack": { "url": "http://localhost:9095/sse", "name": "DeployStack Gateway", "description": "Enterprise MCP Gateway with team-based access control" } } }`

Gateway Endpoints:

- 📡 SSE Connection: http://localhost:9095/sse(for establishing legacy SSE connections) - 📨 Messages:http://localhost:9095/message(for JSON-RPC with session context) - 🚀 MCP Endpoint:http://localhost:9095/mcp(for modern Streamable HTTP transport) - 📊 Health Check:http://localhost:9095/health(for monitoring) - 📋 Status:http://localhost:9095/status (for detailed information)

`📖 Commands`

`$3`

Display version information and check for updates from npm registry.

Options:

- --no-update-check- Skip checking for updates from npm registry ---json- Output version information in JSON format ---debug - Show detailed debug information for npm API calls

Examples:

`bash

`Basic version information with update check`


deploystack version
Skip update check (for offline use)

deploystack version --no-update-check
JSON output for scripts

deploystack version --json
Debug npm API integration

deploystack version --debug


Output when update available:

`text DeployStack Gateway v0.3.0 Built: Mon, Jul 29, 2025, 12:00:00 AM Source: release

Checking npm registry for updates...

📦 Update Available! Current: 0.3.0 Latest: 0.4.0 Package: https://www.npmjs.com/package/@deploystack/gateway Update available! Run: npm install -g @deploystack/gateway@latest

Environment: Node.js: v18.x.x Platform: darwin arm64`

Output when up to date:

`text DeployStack Gateway v0.3.0 Built: Mon, Jul 29, 2025, 12:00:00 AM Source: release

Checking npm registry for updates... ✅ You are running the latest version

Environment: Node.js: v18.x.x Platform: darwin arm64`

`$3`

Manage team context and switch between teams.

Options:

- --switch - Switch to a different team by team number

Examples:

`bash

`List available teams`


deploystack teams
Switch to team #2 (automatically discovers and caches tools)

deploystack teams --switch 2


$3
Refresh MCP server configurations from cloud control plane with automatic change detection and restart prompting.
Options:

- --url - DeployStack backend URL (override stored URL)

Features:

- Change Detection: Automatically detects configuration changes (added/removed/modified servers) - Interactive Restart: Prompts to restart gateway when changes require it - Smart Behavior: Only prompts for restart if gateway is running and changes detected

Examples:

`bash

`Refresh MCP configuration for current team`


deploystack refresh
Refresh with custom backend URL

deploystack refresh --url http://localhost:3000


Sample Output with Changes:

`text 🔄 Refreshing MCP configuration for team: My Team ✅ MCP configuration refreshed (4 servers)

🔄 Configuration changes detected: • brightdata: Environment variables updated • github-server: Arguments changed • new-server: Added to team configuration

⚠️ Gateway restart required for changes to take effect. ? Do you want to restart the DeployStack Gateway now? (Y/n)`

`$3`

Manage MCP server configurations and discover tools.

Options:

- --status- Show MCP configuration status ---refresh- Force refresh MCP configuration from API ---tools - Discover and list tools from a specific MCP server (requires running gateway) ---clear - Clear stored MCP configuration

Examples:

`bash

`Show MCP configuration status`


deploystack mcp
Refresh configuration from cloud

deploystack mcp --refresh
Discover tools from server #1

deploystack mcp --tools 1
Clear stored configuration

deploystack mcp --clear

Note: Both deploystack refresh and deploystack mcp --refresh perform identical operations using shared logic.

`$3`

Start the gateway server as a daemon (background process).

Options:

- -p, --port - Port to run the gateway on (default: 9095) --h, --host - Host to bind the gateway to (default: localhost) --f, --foreground - Run in foreground instead of daemon mode

Examples:

`bash

`Start gateway with SSE endpoints on default port (9095)`


deploystack start
Start on custom port  

deploystack start --port 8080
Run in foreground for debugging

deploystack start --foreground


Output:

`text 🚀 DeployStack Gateway listening at: 📡 SSE endpoint: http://localhost:9095/sse 📨 Messages: http://localhost:9095/message 🚀 MCP endpoint: http://localhost:9095/mcp 📊 Health check: http://localhost:9095/health 🤖 Ready to serve 2 MCP servers for team: kaka`

`$3`

Restart the gateway server with graceful shutdown and startup sequence.

Options:

- -p, --port - Port to run the gateway on (default: 9095) --h, --host - Host to bind the gateway to (default: localhost) --f, --foreground - Run in foreground instead of daemon mode

Features:

- Graceful Shutdown: Properly stops all MCP server processes before restart - Smart Behavior: If gateway isn't running, performs a start operation instead - Configuration Reload: Picks up any configuration changes after restart

Examples:

`bash

`Restart gateway with current configuration`


deploystack restart
Restart on custom port

deploystack restart --port 8080
Restart in foreground for debugging

deploystack restart --foreground


$3
Stop the running gateway server.
Options:

- -f, --force - Force stop the server (SIGKILL instead of SIGTERM)

Examples:

`bash

`Graceful shutdown`


deploystack stop
Force shutdown

deploystack stop --force


$3
Show detailed gateway status including running processes.
Options:

- -j, --json- Output status as JSON --v, --verbose - Show detailed process information

Examples:

`bash

`Basic status`


deploystack status
Detailed status with process info

deploystack status --verbose
JSON output for scripting

deploystack status --json


$3
Show all connected MCP clients with detailed connection information.
Examples:

`bash

`Show connected clients`


deploystack clients


Features:
- Real-time Status: Shows currently connected MCP clients from cache
- Connection Types: Displays both SSE and Streamable HTTP connections
- Activity Tracking: Shows last activity time and request counts
- Client Information: Displays client name, version, and user agent when available
- Connection Endpoints: Lists all available gateway endpoints
- Cache Integration: Uses client state cache for accurate connection tracking
Sample Output:

`text Connected MCP Clients ══════════════════════════════════════════════════

Summary: 2 active connections • SSE connections: 1 • Streamable HTTP connections: 1 • Initialized clients: 2 • Active (last 5min): 2

Client Details:

VS Code v1.95.0 ID: sse_abc123 Type: SSE Initialized Activity: 30s ago (15 requests) Uptime: 2h 15m User Agent: VSCode/1.95.0

Cursor v0.42.0 ID: http_def456 Type: Streamable HTTP Initialized Activity: 1m ago (8 requests) Uptime: 45m 30s

Connection Endpoints: • SSE: http://localhost:9095/sse • Messages: http://localhost:9095/message • MCP: http://localhost:9095/mcp • Health: http://localhost:9095/health

Cache last updated: 1/4/2025, 9:30:15 AM`

`🛠️ Troubleshooting`

`$3`

VS Code not connecting:

`bash

`Check if gateway is running`


deploystack status
Verify endpoints are responding

curl http://localhost:9095/health
Test SSE connection

curl -N -H "Accept: text/event-stream" http://localhost:9095/sse


No tools available:

`bash

`Check if team is selected`


deploystack teams
Refresh team configuration

deploystack mcp --refresh
Restart gateway to reload config

deploystack stop && deploystack start


Authentication issues:

`bash

`Re-authenticate`


deploystack logout
deploystack login
Check stored credentials

deploystack whoami

$3

`bash

`Check version and updates`


deploystack version
Run in foreground to see detailed logs

deploystack start --foreground
Debug npm API integration

deploystack version --debug
Check process status

deploystack status --verbose

$3

Automatic Updates: The gateway automatically checks for updates when you run deploystack version. You'll be notified if a newer version is available on npm.

Update Process:

`bash

`Check for updates`


deploystack version
If update available, install latest version

npm install -g @deploystack/gateway@latest
Verify new version

deploystack version

Offline Mode: Use --no-update-check flag to skip version checking when working offline.

`🕰️ Version History`

`🤝 Contributing`

We welcome contributions! This is a new service in active development with a modern SSE-based architecture.

Key areas for contribution:

- SSE Transport: Enhancing session management and connection reliability - Process Management: Improving MCP server lifecycle and team isolation - Security: Strengthening credential handling and session security - Performance: Optimizing persistent process communication - VS Code Integration: Improving MCP client compatibility - Enterprise Features: Team management and access control enhancements

Development Setup:

`bash

`Clone and setup`


git clone 
cd services/gateway
npm install
Development mode

npm run dev
Build and test

npm run build
node dist/index.js start --foreground

For detailed contribution guidelines, see CONTRIBUTING.md in the project root.

DeployStack Gateway

🔍 Features

🛠️ Installation

``bash

`Installation command coming soon`


npm install -g @deploystack/gateway


🚀 Usage

`bash

`Login to your DeployStack account (automatically starts the gateway)`


deploystack login
Check status

deploystack status
Or start the gateway manually if needed

deploystack start


🧱 How It Works

`📋 Prerequisites`

- Node.js (v18 or higher) - npm (v8 or higher) - A DeployStack account at cloud.deploystack.io

`🏗️ Architecture`

`$3`

The DeployStack Gateway implements a modern dual-endpoint SSE architecture for VS Code compatibility:

`text 1. Client connects: GET /sse 2. Gateway responds: SSE stream + session endpoint 3. Client sends: POST /message?session=xyz (JSON-RPC) 4. Gateway responds: Via SSE stream (real-time)`

Connection Flow:

Benefits:

`$3`

The gateway runs MCP servers as persistent background processes:

`🔧 Configuration`

After logging in, the gateway automatically downloads and synchronizes your team's configuration. No manual configuration required!

VS Code/Cursor Configuration:

`json { "mcpServers": { "deploystack": { "url": "http://localhost:9095/sse", "name": "DeployStack Gateway", "description": "Enterprise MCP Gateway with team-based access control" } } }`

Gateway Endpoints:

`📖 Commands`

`$3`

Display version information and check for updates from npm registry.

Options:

- --no-update-check- Skip checking for updates from npm registry ---json- Output version information in JSON format ---debug - Show detailed debug information for npm API calls

Examples:

`bash

`Basic version information with update check`


deploystack version
Skip update check (for offline use)

deploystack version --no-update-check
JSON output for scripts

deploystack version --json
Debug npm API integration

deploystack version --debug


Output when update available:

`text DeployStack Gateway v0.3.0 Built: Mon, Jul 29, 2025, 12:00:00 AM Source: release

Checking npm registry for updates...

📦 Update Available! Current: 0.3.0 Latest: 0.4.0 Package: https://www.npmjs.com/package/@deploystack/gateway Update available! Run: npm install -g @deploystack/gateway@latest

Environment: Node.js: v18.x.x Platform: darwin arm64`

Output when up to date:

`text DeployStack Gateway v0.3.0 Built: Mon, Jul 29, 2025, 12:00:00 AM Source: release

Checking npm registry for updates... ✅ You are running the latest version

Environment: Node.js: v18.x.x Platform: darwin arm64`

`$3`

Manage team context and switch between teams.

Options:

- --switch - Switch to a different team by team number

Examples:

`bash

`List available teams`


deploystack teams
Switch to team #2 (automatically discovers and caches tools)

deploystack teams --switch 2


$3
Refresh MCP server configurations from cloud control plane with automatic change detection and restart prompting.
Options:

- --url - DeployStack backend URL (override stored URL)

Features:

Examples:

`bash

`Refresh MCP configuration for current team`


deploystack refresh
Refresh with custom backend URL

deploystack refresh --url http://localhost:3000


Sample Output with Changes:

`text 🔄 Refreshing MCP configuration for team: My Team ✅ MCP configuration refreshed (4 servers)

🔄 Configuration changes detected: • brightdata: Environment variables updated • github-server: Arguments changed • new-server: Added to team configuration

⚠️ Gateway restart required for changes to take effect. ? Do you want to restart the DeployStack Gateway now? (Y/n)`

`$3`

Manage MCP server configurations and discover tools.

Options:

Examples:

`bash

`Show MCP configuration status`


deploystack mcp
Refresh configuration from cloud

deploystack mcp --refresh
Discover tools from server #1

deploystack mcp --tools 1
Clear stored configuration

deploystack mcp --clear

Note: Both deploystack refresh and deploystack mcp --refresh perform identical operations using shared logic.

`$3`

Start the gateway server as a daemon (background process).

Options:

- -p, --port - Port to run the gateway on (default: 9095) --h, --host - Host to bind the gateway to (default: localhost) --f, --foreground - Run in foreground instead of daemon mode

Examples:

`bash

`Start gateway with SSE endpoints on default port (9095)`


deploystack start
Start on custom port  

deploystack start --port 8080
Run in foreground for debugging

deploystack start --foreground


Output:

`$3`

Restart the gateway server with graceful shutdown and startup sequence.

Options:

- -p, --port - Port to run the gateway on (default: 9095) --h, --host - Host to bind the gateway to (default: localhost) --f, --foreground - Run in foreground instead of daemon mode

Features:

Examples:

`bash

`Restart gateway with current configuration`


deploystack restart
Restart on custom port

deploystack restart --port 8080
Restart in foreground for debugging

deploystack restart --foreground


$3
Stop the running gateway server.
Options:

- -f, --force - Force stop the server (SIGKILL instead of SIGTERM)

Examples:

`bash

`Graceful shutdown`


deploystack stop
Force shutdown

deploystack stop --force


$3
Show detailed gateway status including running processes.
Options:

- -j, --json- Output status as JSON --v, --verbose - Show detailed process information

Examples:

`bash

`Basic status`


deploystack status
Detailed status with process info

deploystack status --verbose
JSON output for scripting

deploystack status --json


$3
Show all connected MCP clients with detailed connection information.
Examples:

`bash

`Show connected clients`


deploystack clients


Features:
- Real-time Status: Shows currently connected MCP clients from cache
- Connection Types: Displays both SSE and Streamable HTTP connections
- Activity Tracking: Shows last activity time and request counts
- Client Information: Displays client name, version, and user agent when available
- Connection Endpoints: Lists all available gateway endpoints
- Cache Integration: Uses client state cache for accurate connection tracking
Sample Output:

`text Connected MCP Clients ══════════════════════════════════════════════════

Summary: 2 active connections • SSE connections: 1 • Streamable HTTP connections: 1 • Initialized clients: 2 • Active (last 5min): 2

Client Details:

VS Code v1.95.0 ID: sse_abc123 Type: SSE Initialized Activity: 30s ago (15 requests) Uptime: 2h 15m User Agent: VSCode/1.95.0

Cursor v0.42.0 ID: http_def456 Type: Streamable HTTP Initialized Activity: 1m ago (8 requests) Uptime: 45m 30s

Connection Endpoints: • SSE: http://localhost:9095/sse • Messages: http://localhost:9095/message • MCP: http://localhost:9095/mcp • Health: http://localhost:9095/health

Cache last updated: 1/4/2025, 9:30:15 AM`

`🛠️ Troubleshooting`

`$3`

VS Code not connecting:

`bash

`Check if gateway is running`


deploystack status
Verify endpoints are responding

curl http://localhost:9095/health
Test SSE connection

curl -N -H "Accept: text/event-stream" http://localhost:9095/sse


No tools available:

`bash

`Check if team is selected`


deploystack teams
Refresh team configuration

deploystack mcp --refresh
Restart gateway to reload config

deploystack stop && deploystack start


Authentication issues:

`bash

`Re-authenticate`


deploystack logout
deploystack login
Check stored credentials

deploystack whoami

$3

`bash

`Check version and updates`


deploystack version
Run in foreground to see detailed logs

deploystack start --foreground
Debug npm API integration

deploystack version --debug
Check process status

deploystack status --verbose

$3

Automatic Updates: The gateway automatically checks for updates when you run deploystack version. You'll be notified if a newer version is available on npm.

Update Process:

`bash

`Check for updates`


deploystack version
If update available, install latest version

npm install -g @deploystack/gateway@latest
Verify new version

deploystack version

Offline Mode: Use --no-update-check flag to skip version checking when working offline.

`🕰️ Version History`

`🤝 Contributing`

We welcome contributions! This is a new service in active development with a modern SSE-based architecture.

Key areas for contribution:

Development Setup:

`bash

`Clone and setup`


git clone 
cd services/gateway
npm install
Development mode

npm run dev
Build and test

npm run build
node dist/index.js start --foreground

For detailed contribution guidelines, see CONTRIBUTING.md in the project root.