RealWorker Manager Server

Overview

This is a Manager/Admin MCP (Model Context Protocol) Server that coordinates and monitors multiple worker MCP servers across a distributed network. It acts as a centralized control plane for managing worker nodes. This is a Manager/Admin MCP (Model Context Protocol) Server that coordinates and monitors multiple worker MCP servers across a distributed network. It acts as a centralized control plane for managing worker nodes.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                      MCP Client (Claude/AI)                     │
│                                                                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ STDIO
                            │ (Standard Input/Output)
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                    ADMIN/MANAGER SERVER                         │
│                   (admin_server/admin.py)                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              FastMCP Server Core                        │    │
│  │  - Server Name: "Manager"                               │    │
│  │  - Transport: STDIO                                     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Management Tools                           │    │
│  │                                                         │    │
│  │  1. get_all_workers_status()                            │    │
│  │     - Polls all workers simultaneously                  │    │
│  │     - Returns aggregated status                         │    │
│  │                                                         │    │
│  │  2. get_worker_status(worker_name)                      │    │
│  │     - Gets status from specific worker                  │    │
│  │     - Returns detailed worker info                      │    │
│  │                                                         │    │
│  │  3. list_workers()                                      │    │
│  │     - Lists all configured workers                      │    │
│  │     - Returns worker URLs                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │           Worker Registry (WORKERS dict)                │    │
│  │                                                         │    │
│  │  Worker-One: http://10.149.14.61:8000                   │    │
│  │  [Additional workers can be added here]                 │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└───────────┬─────────────────────────────────┬───────────────────┘
            │ HTTP/HTTPX                      │ HTTP/HTTPX
            │ (Async Client)                  │ (Async Client)
            │                                 │
┌───────────▼─────────────┐       ┌──────────▼──────────────┐
│   WORKER-ONE SERVER     │       │   WORKER-N SERVER       │
│   (10.149.14.61:8000)   │       │   (Additional Workers)  │
│                         │       │                         │
│  ┌──────────────────┐   │       │  ┌──────────────────┐   │
│  │ MCP Worker Core  │   │       │  │ MCP Worker Core  │   │
│  │ - SSE Endpoints  │   │       │  │ - SSE Endpoints  │   │
│  │ - Tool Handler   │   │       │  │ - Tool Handler   │   │
│  └──────────────────┘   │       │  └──────────────────┘   │
│                         │       │                         │
│  ┌──────────────────┐   │       │  ┌──────────────────┐   │
│  │ Worker Tools     │   │       │  │ Worker Tools     │   │
│  │ - System Status  │   │       │  │ - System Status  │   │
│  │ - Battery Info   │   │       │  │ - Battery Info   │   │
│  │ - Custom Tasks   │   │       │  │ - Custom Tasks   │   │
│  └──────────────────┘   │       │  └──────────────────┘   │
│                         │       │                         │
└─────────────────────────┘       └─────────────────────────┘

Component Details

1. Admin/Manager Server (admin.py)

Purpose: Central coordination server that manages multiple worker MCP servers

Key Components:

• FastMCP Core: Lightweight MCP server framework
• Worker Registry: Dictionary mapping worker names to URLs
• HTTP Client: Async HTTPX client for worker communication
• Management Tools: Three exposed tools for worker management

Communication:

• Upstream (to AI Client): STDIO transport
• Downstream (to Workers): HTTP POST requests to worker SSE endpoints

2. Worker Servers

Purpose: Distributed worker nodes that perform actual tasks and report status

Key Components:

• MCP Server Core: Handles incoming requests via SSE
• Tool Endpoints: /sse/tools/call for tool execution
• Status Tools: get_worker_status() and other worker-specific tools

Communication:

• Upstream (to Admin): HTTP responses to manager requests
• Local Resources: Access to system information (CPU, memory, battery, etc.)

Data Flow

Scenario 1: Get All Workers Status

1. AI Client → Admin: Call get_all_workers_status()
2. Admin → Worker-One: POST /sse/tools/call (get_worker_status)
3. Admin → Worker-N: POST /sse/tools/call (get_worker_status)
   [Parallel async requests]
4. Worker-One → Admin: Return status data
5. Worker-N → Admin: Return status data
6. Admin → AI Client: Aggregated results from all workers

Scenario 2: Get Specific Worker Status

1. AI Client → Admin: Call get_worker_status("Worker-One")
2. Admin: Lookup worker URL from WORKERS registry
3. Admin → Worker-One: POST /sse/tools/call (get_worker_status)
4. Worker-One → Admin: Return status data
5. Admin → AI Client: Worker status

Scenario 3: List Workers

1. AI Client → Admin: Call list_workers()
2. Admin: Return WORKERS dictionary
3. Admin → AI Client: List of workers with URLs

Technical Stack

Core Technologies

• Python 3.11+: Runtime environment
• FastMCP: MCP server framework
• HTTPX: Async HTTP client for worker communication
• STDIO: Transport protocol for AI client communication

Dependencies

httpx>=0.28.1       # Async HTTP client
mcp[cli]>=1.26.0    # MCP framework
psutil>=7.2.2       # System monitoring (likely used by workers)
uvicorn>=0.40.0     # ASGI server (for workers)

Deployment Architecture

Network Layer:
┌─────────────────────────────────────────────────────────┐
│                    Local Network / VPN                   │
│                                                          │
│  Admin Server         Worker-One         Worker-N       │
│  (localhost)          (10.149.14.61)     (10.x.x.x)     │
│                                                          │
└─────────────────────────────────────────────────────────┘

Deployment Characteristics:

• Admin runs locally and communicates via STDIO with AI client
• Workers are distributed across network (LAN/VPN)
• HTTP-based communication between admin and workers
• 10-second timeout for worker requests
• Async/parallel communication for efficiency

Security Considerations

1. Network Security:

   • Workers expose HTTP endpoints (currently unencrypted)
   • Should be deployed on trusted network or use VPN
   • Consider adding HTTPS/TLS for production

2. Authentication:

   • Currently no authentication between admin and workers
   • Consider adding API keys or mutual TLS

3. Error Handling:

   • Graceful degradation when workers are unavailable
   • Timeout protection (10s) prevents hanging

Scalability

Current Design:

• Synchronous registry (WORKERS dict)
• Hardcoded worker URLs
• Manual configuration

Future Improvements:

• Service discovery mechanism
• Dynamic worker registration
• Health check automation
• Load balancing across workers
• Worker heartbeat monitoring

Extension Points

1. Add New Worker: Update WORKERS dictionary with new worker URL
2. Add New Tool: Define new @mcp.tool() function in admin.py
3. Custom Worker Communication: Extend HTTP client logic
4. Monitoring: Add logging, metrics collection, alerting

Usage Example

# From AI Client (Claude)
# The admin server exposes these tools:

# 1. List all configured workers
list_workers()
# Returns: {"workers": {"Worker-One": "http://10.149.14.61:8000"}}

# 2. Get status from all workers
get_all_workers_status()
# Returns: {"Worker-One": {...status data...}}

# 3. Get status from specific worker
get_worker_status("Worker-One")
# Returns: {...status data from Worker-One...}

Running the Server

# Development mode
uv run admin.py

# Production mode (via MCP configuration)
# Add to Claude Desktop config:
{
  "mcpServers": {
    "admin-server": {
      "command": "uv",
      "args": ["run", "admin.py"],
      "cwd": "d:\\SLT\\AI\\MCP_Servers\\admin_server"
    }
  }
}

Project Structure

admin_server/
├── admin.py           # Main admin/manager server
├── main.py           # Alternative entry point (unused)
├── pyproject.toml    # Project dependencies
└── README.md         # This architecture document