docs: update satellite architecture and commands documentation to reflect completed MCP server management features and tool discovery enhancements

Author: Lasim

docs/development/satellite/architecture.mdx

@@ -315,21 +315,24 @@ For complete implementation details, see [Backend Polling Implementation](/devel
 - **Scope-Based Access**: Fine-grained permissions
 - **Team Context**: Automatic team resolution from tokens
 
-## MCP Server Management (Planned)
+## MCP Server Management
 
 ### Dual MCP Server Support
 
 **stdio Subprocess Servers:**
-- **Local Execution**: MCP servers as child processes
-- **JSON-RPC Communication**: Standard MCP protocol
-- **Process Lifecycle**: Spawn, monitor, terminate
-- **Team Isolation**: Processes isolated per team
+- **Local Execution**: MCP servers as Node.js child processes
+- **JSON-RPC Communication**: Full MCP protocol 2025-11-05 over stdin/stdout
+- **Process Lifecycle**: Spawn, monitor, auto-restart (max 3 attempts), terminate
+- **Team Isolation**: Processes tracked by team_id with environment-based security
+- **Tool Discovery**: Automatic tool caching with namespacing
+- **Resource Limits**: nsjail in production (100MB RAM, 60s CPU, 50 processes)
+- **Development Mode**: Plain spawn() on all platforms for easy debugging
 
 **HTTP Proxy Servers:**
 - **External Endpoints**: Proxy to remote MCP servers
 - **Load Balancing**: Distribute requests across instances
 - **Health Monitoring**: Endpoint availability checks
-- **Caching**: Response caching for performance
+- **Tool Discovery**: Automatic at startup from remote endpoints
 
 ### Process Management
 
@@ -357,11 +360,13 @@ Configuration → Spawn → Monitor → Health Check → Restart/Terminate
 - **Session Management**: Cryptographically secure session handling
 - **JSON-RPC 2.0**: Full protocol compliance with error handling
 
-### Phase 2: MCP Server Process Management (Next)
-- **Process Lifecycle**: Spawn, monitor, terminate MCP servers
-- **stdio Communication**: JSON-RPC with local processes
-- **Basic Health Monitoring**: Process health checks
-- **Simple Configuration**: Static MCP server definitions
+### Phase 2: MCP Server Process Management ✅ COMPLETED
+- **Process Lifecycle**: Spawn, monitor, terminate MCP servers with auto-restart
+- **stdio Communication**: JSON-RPC 2.0 over stdin/stdout with buffer-based parsing
+- **Tool Discovery**: Discover and cache tools from stdio MCP servers
+- **Health Monitoring**: Process health checks and crash detection
+- **Auto-Restart**: Max 3 attempts with exponential backoff, then permanently_failed status
+- **Team-Aware Reporting**: processes_by_team in heartbeat every 30 seconds
 
 ### Phase 3: Team Isolation
 - **Resource Boundaries**: CPU and memory limits
@@ -469,9 +474,3 @@ The satellite service has completed **Phase 1: MCP Transport Implementation** an
 - **Logging System**: Pino with structured logging
 - **Build Pipeline**: TypeScript compilation and bundling
 - **Development Workflow**: Hot reload and code quality tools
-
-Next milestone: **Phase 2 - MCP Server Process Management** with stdio JSON-RPC communication.
-
-<Callout type="info">
-**Current Status**: The satellite service has completed Phase 1 (MCP Transport Implementation) and Phase 4 (Backend Integration). It provides full external client interface support and complete backend communication including command orchestration, configuration management, and status reporting. The next major milestone is implementing MCP server process management (Phase 2) to enable actual MCP server hosting.
-</Callout>

docs/development/satellite/commands.mdx

@@ -55,10 +55,14 @@ Each satellite command contains:
 **Satellite Actions**:
 1. Fetch updated MCP server configurations from backend
 2. Compare with existing configurations using hash-based change detection
-3. Spawn new MCP server processes for added/modified servers
-4. Terminate MCP server processes for deleted installations
-5. Update HTTP proxy routes for new/removed MCP servers
-6. Perform tool discovery on newly spawned servers
+3. Spawn new MCP servers based on transport type:
+   - **stdio transport**: Spawn Node.js subprocess via ProcessManager
+   - **HTTP transport**: Configure HTTP proxy routes
+4. Terminate MCP servers for deleted installations:
+   - **stdio transport**: Graceful process termination (SIGTERM → SIGKILL)
+   - **HTTP transport**: Remove proxy routes
+5. Perform tool discovery on newly spawned/configured servers
+6. Report process status to backend via team-grouped heartbeat
 
 ### restart
 

docs/development/satellite/index.mdx

@@ -13,7 +13,7 @@ DeployStack Satellites are **edge workers** (similar to GitHub Actions runners)
 
 ## Current Implementation Status
 
-The satellite service has completed **Phase 1: MCP Transport Implementation** with working external client interfaces:
+:The satellite service has completed
 
 - ✅ **Fastify HTTP Server** with Swagger API documentation
 - ✅ **Pino Logging System** identical to backend configuration
@@ -22,10 +22,12 @@ The satellite service has completed **Phase 1: MCP Transport Implementation** wi
 - ✅ **JSON-RPC 2.0 Protocol** compliance for MCP communication
 - ✅ **TypeScript + Webpack** build system with full type safety
 - ✅ **Development Workflow** with hot reload and linting
-- ✅ **Backend Communication** (polling, commands, heartbeat)
+- ✅ **Backend Communication** (polling, commands, heartbeat with team-grouped processes)
 - ✅ **OAuth 2.1 Authentication** (token introspection, team context)
-- 🚧 **MCP Server Process Management** (ready for implementation)
-- 🚧 **Team Isolation with nsjail** (ready for implementation)
+- ✅ **stdio MCP Server Process Management** (spawn, monitor, auto-restart, terminate)
+- ✅ **Team Isolation** (environment-based: nsjail in production, plain spawn in dev)
+- ✅ **Auto-Restart Protection** (max 3 attempts, permanently_failed status)
+- ✅ **Tool Discovery** (HTTP and stdio MCP servers)
 
 ## Architecture Vision
 
@@ -218,14 +220,16 @@ curl -X POST http://localhost:3001/mcp \
 - **Build System**: TypeScript compilation with Webpack bundling
 - **Release Management**: Conventional changelog with release-it
 
-## Planned Features (Roadmap)
+## Implemented Features
 
-### Phase 2: MCP Server Process Management (Ready for Implementation)
-- **Process Lifecycle**: Spawn, monitor, and terminate MCP server processes with nsjail
-- **stdio Communication**: JSON-RPC communication with local MCP servers
-- **HTTP Proxy**: Reverse proxy for external MCP server endpoints (already working)
-- **Health Monitoring**: Process health checks and automatic restart
-- **Resource Limits**: 100MB RAM, 60s CPU, 50 processes per server (via nsjail)
+### Phase 2: MCP Server Process Management ✅ COMPLETED
+- **Process Lifecycle**: Spawn, monitor, auto-restart (max 3), and terminate MCP servers
+- **stdio Communication**: Full JSON-RPC 2.0 protocol over stdin/stdout
+- **HTTP Proxy**: Reverse proxy for external MCP server endpoints ✅ working
+- **Health Monitoring**: Process crash detection with auto-restart
+- **Resource Limits**: nsjail with 100MB RAM, 60s CPU, 50 processes (production Linux)
+- **Tool Discovery**: Automatic tool caching from both HTTP and stdio servers
+- **Team-Grouped Heartbeat**: processes_by_team reporting every 30 seconds
 
 ### Phase 3: Team Isolation (Infrastructure Ready)
 - **nsjail Sandboxing**: Complete process isolation with built-in resource limits
@@ -298,8 +302,3 @@ When contributing to satellite development:
 5. **Consider Enterprise**: Design features with team isolation and security in mind
 6. **MCP Compliance**: Ensure JSON-RPC 2.0 protocol compliance
 
-## Next Steps
-
-The satellite service has completed Phase 1 (MCP Transport Implementation) and is ready for Phase 2 development. The next major milestone is implementing MCP server process management, which will enable the core satellite functionality of managing MCP servers on behalf of teams.
-
-For detailed implementation guidance, see the architecture and MCP transport documentation linked above.