# 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.

## Architecture Diagram

```text

┌─────────────────────────────────────────────────────────────────┐
│                      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

```python
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

```text
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

```text
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

```toml
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

```text
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

```python
# 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

```bash
# 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

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