replica-omnisciente/.aurelio/mcp/README.md

MCP Servers Configuration

This directory contains all Model Context Protocol (MCP) server configurations and implementations for the savearth infrastructure.

Overview

Server	Purpose	Location	Status
openclaw	Proxmox infrastructure gateway	CT 207	✅ Running
savearth-mcp	Unified telemetry/device MCP	CT 201	✅ Running

---

Quick Start

1. Get Required Tokens

# OpenClaw gateway token (for infrastructure access)
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw config get gateway.auth.token"

2. Choose Your MCP Client

Select the configuration for your AI assistant:

• Kimi Code
• Claude Desktop
• VS Code / Cursor
• Generic MCP Client

3. Test Connection

# Test OpenClaw
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw health"

# Expected output:
# Kimi Claw: ok
# Agents: main (default)

---

MCP Server: OpenClaw

Access 50+ skills for infrastructure management, development, and communication.

Capabilities

Category	Skills
Infrastructure	Shell execution, Proxmox containers (pct), device discovery, health checks
Development	GitHub operations, coding agents, CI/CD, firmware builds
Communication	Slack, Discord, Telegram, email (Himalaya)
Productivity	Notion, Obsidian, Trello, calendar, reminders

Configuration

Kimi Code

File: ~/.config/kimi-code/mcp.json

{
  "mcpServers": {
    "openclaw-proxmox": {
      "command": "ssh",
      "args": [
        "ssh.portugalfuturista.org",
        "pct exec 207 -- openclaw mcp serve --token YOUR_GATEWAY_TOKEN"
      ],
      "env": {}
    }
  }
}

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "openclaw-proxmox": {
      "command": "ssh",
      "args": [
        "ssh.portugalfuturista.org",
        "pct exec 207 -- openclaw mcp serve --token YOUR_GATEWAY_TOKEN"
      ]
    }
  }
}

Windows: %APPDATA%/Claude/claude_desktop_config.json

VS Code / Cursor

File: .vscode/mcp.json or settings.json

{
  "mcp.servers": {
    "openclaw-proxmox": {
      "command": "ssh",
      "args": [
        "ssh.portugalfuturista.org",
        "pct exec 207 -- openclaw mcp serve --token YOUR_GATEWAY_TOKEN"
      ]
    }
  }
}

Generic MCP Client

{
  "mcpServers": {
    "openclaw-proxmox": {
      "name": "OpenClaw Proxmox Gateway",
      "description": "Access 50+ skills for infrastructure management",
      "command": "ssh",
      "args": [
        "ssh.portugalfuturista.org",
        "pct exec 207 -- openclaw mcp serve --token YOUR_GATEWAY_TOKEN"
      ],
      "capabilities": {
        "tools": true,
        "resources": false,
        "prompts": false
      }
    }
  }
}

Usage Examples

User: List all LXC containers
→ AI uses shell tool: pct list

User: Check health of HIL devices
→ AI uses device_discover and health_check tools

User: Send Slack message to #infrastructure
→ AI uses slack_send tool (if configured)

Documentation

• Full guide: openclaw/README.md
• Quick start: openclaw/QUICKSTART.md
• Skills reference: openclaw/skills/
• Workflows: openclaw/workflows/

---

MCP Server: savearth Unified

Unified MCP server for telemetry, device management, and infrastructure queries.

Capabilities

• Device telemetry queries (InfluxDB)
• Fleet health checks (DynamoDB)
• MQTT connection analysis
• Shower session analytics
• FSM transition monitoring

Configuration

Endpoint: http://192.168.0.212:8080/sse (CT 201)

{
  "mcpServers": {
    "savearth": {
      "url": "http://192.168.0.212:8080/sse",
      "transport": "sse"
    }
  }
}

Available Tools

Tool	Description
query_telemetry	Query InfluxDB for device metrics
get_device_status	Get latest device telemetry status
get_volume_history	Get water volume consumption history
analyze_connections	Analyze MQTT connection drops
fleet_overview	List all devices with last-seen time
get_shower_sessions	Analyze shower sessions
query_dynamodb_logs	Browse device logs from DynamoDB
analyze_fsm_transitions	Parse FSM state transitions
fleet_health_check	Run fleet-wide health check

Usage Examples

User: Show me the water consumption for device dc:b4:d9:01:58:38
→ AI queries InfluxDB and returns volume history

User: Check fleet health
→ AI runs health check across all devices

User: Analyze FSM transitions for device in last hour
→ AI parses DynamoDB logs for state transitions

Setup

The server runs on CT 201 (savearth-mcp). To deploy or update:

# From Proxmox host
bash .agent/mcp/setup.sh 201

# Or manually
pct exec 201 -- systemctl restart savearth-mcp

Documentation

• Server code: savearth-mcp/server.py
• Setup script: setup.sh

---

Helper Scripts

Located in openclaw/scripts/:

Script	Purpose
get-token.sh	Retrieve OpenClaw gateway token
test-connection.sh	Test full MCP connection chain
list-tools.sh	List available OpenClaw skills

Usage

# Get token
./openclaw/scripts/get-token.sh

# Test connection
./openclaw/scripts/test-connection.sh

# List all tools
./openclaw/scripts/list-tools.sh --all

---

Security Notes

Token Management

• Never commit tokens to version control
• Use environment variables when possible
• Rotate tokens periodically
• The gateway token provides full OpenClaw access

SSH Access

All MCP connections use SSH tunneling for encryption:

• Entry point: ssh.portugalfuturista.org
• Cloudflare tunnel for secure external access
• No direct port exposure

Container Security

• OpenClaw runs in unprivileged container (CT 207)
• No root access to Proxmox host
• Skills are sandboxed

---

Troubleshooting

Connection Refused

# Check if OpenClaw is running
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw health"

# Restart if needed
ssh ssh.portugalfuturista.org "pct exec 207 -- pkill openclaw-gateway"
ssh ssh.portugalfuturista.org "pct exec 207 -- bash -c 'nohup openclaw gateway run > /var/log/openclaw.log 2>&1 &'"

Authentication Failed

# Get current token
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw config get gateway.auth.token"

SSH Timeout

# Check connectivity
ping ssh.portugalfuturista.org

# Check Cloudflare tunnel
ssh ssh.portugalfuturista.org "systemctl status cloudflared"

MCP Tools Not Loading

# Check OpenClaw skills
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw skills list"

# Check plugin status
ssh ssh.portugalfuturista.org "pct exec 207 -- openclaw plugins list"

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  AI CLIENT (Kimi Code, Claude, VS Code)                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  MCP Client                                               │  │
│  └────────────────────┬──────────────────────────────────────┘  │
└───────────────────────┼─────────────────────────────────────────┘
                        │ MCP protocol (stdio or SSE)
┌───────────────────────┼─────────────────────────────────────────┐
│  PROXMOX HOST         │                                         │
│  (ssh.portugalfuturista.org)                                    │
│                       ▼                                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  CT 207: openclaw-gateway                                  │  │
│  │  ┌─────────────────────────────────────────────────────┐   │  │
│  │  │  OpenClaw MCP Server                                 │   │  │
│  │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │  │
│  │  │  │ Infrastructure│  │ Development │  │ Communication│  │   │  │
│  │  │  │ Skills      │  │ Skills      │  │ Skills      │  │   │  │
│  │  │  └─────────────┘  └─────────────┘  └─────────────┘  │   │  │
│  │  └─────────────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  CT 201: savearth-mcp                                      │  │
│  │  (Unified telemetry/device MCP)                            │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

---

References

• OpenClaw Documentation
• MCP Protocol Specification
• Project AGENTS.md

---

Updates

To update MCP configurations:

1. Edit the relevant files in this directory
2. Test with test-connection.sh
3. Reload your MCP client
4. Verify with a simple query like "What tools are available?"