Skip to main content
Glama
RealWorker-Manager MCP Server

RealWorker-Manager MCP Server

by Lalindu0923

MCP Admin Server Architecture

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.

Related MCP server: MCP Proxy Server

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

Available Tools

5 tools
get_all_workers_system_statsB

Returns system statistics for all workers.

Inputs: no named parameters.

get_system_stats_by_locationB

Returns system stats of workers filtered by floor and section.

Inputs: floor (required), section (required).

get_worker_infoB

Returns battery percentage and charging status of a worker.

Inputs: worker_name (required).

get_worker_system_statsC

Returns full system statistics of a specific worker.

Inputs: worker_name (required).

list_workersA

Returns a summary of all real workers including IP, floor, section, and connection status.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    Most tools are clearly distinct: list_workers for summaries, get_worker_info for battery/charging, and three system stats variants for different scopes. However, get_worker_info and get_worker_system_stats could be confused if an agent overlooks the specific fields, since system stats may include battery data.

    Naming Consistency4/5

    Tools consistently use verbs (list/get) followed by nouns, and all are snake_case. Minor inconsistency exists in noun phrasing (e.g., get_system_stats_by_location vs get_worker_system_stats vs get_all_workers_system_stats), but the pattern remains predictable overall.

    Tool Count5/5

    With 5 tools, the server is well-scoped for a real-worker management/monitoring domain. Each tool covers a distinct retrieval need, and the count feels neither too sparse nor excessive.

    Completeness4/5

    The server covers core read-only operations: listing workers, getting individual details, and fetching system stats at various granularities. Minor gaps exist, such as no dedicated tool for a specific worker's connection status beyond the list, but agents can work around this by filtering list_workers.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables centralized management and unified interface for multiple child MCP servers (filesystem, sqlite, etc.), allowing users to discover, launch, and execute tools across different MCP servers through a single gateway.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables discovering and managing MCP servers through a registry, supporting listing, searching, and configuration.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables centralized management of MCP servers across multiple AI coding harnesses, including adding, removing, monitoring, configuring, and syncing servers with encrypted token storage.
      15 PyPI
      MIT