SaferPlaces MCP Server

Server MCP che espone i processi di simulazione delle REST API di SaferPlaces come tool utilizzabili da Claude, per lanciare e monitorare simulazioni direttamente dalla chat.

Processi supportati (descrizioni lette live dal server, nei formati f=json e f=jsonld):

• untrim-process — modello UNTRIM, water depth da pioggia e DEM

• digital-twin-process — preparazione DEM (edifici, land use, extrusion, seamask)

• terra-twin-process

Per aggiungere un processo basta inserire il suo id in PROCESS_IDS (e nel Literal associato) in cima a saferplaces_mcp.py.

Le credenziali (utente e token) vengono iniettate dal server nel body di ogni richiesta di esecuzione: non passano mai per la chat e Claude non le vede. I nomi dei campi (user e token, dentro inputs) sono verificati sulla descrizione live dei processi.

Tool esposti

Related MCP server: MCP OpenAPI Connector

Struttura del repo

saferplaces_mcp.py    # il server MCP
requirements.txt      # dipendenze Python (fastmcp, httpx)
README.md

Configurazione

Il server richiede due variabili d'ambiente:

In cima a saferplaces_mcp.py ci sono tre costanti da verificare rispetto alla documentazione delle API:

• USER_FIELD e TOKEN_FIELD: i nomi esatti dei campi del body in cui l'API si aspetta le credenziali (default: user e token).

• CREDENTIALS_INSIDE_INPUTS: True se le credenziali vanno annidate dentro l'oggetto inputs del body (tipico delle OGC API Processes), False se vanno al livello principale.

Uso locale (Claude Code / Claude Desktop)

Richiede Python 3.10+.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export SAFERPLACES_USER="tuo-utente"
export SAFERPLACES_TOKEN="tuo-token"

# test rapido: deve avviarsi senza errori (Ctrl+C per fermarlo)
python saferplaces_mcp.py

Collegamento a Claude Code (usa i percorsi assoluti):

claude mcp add saferplaces \
  -e SAFERPLACES_USER=tuo-utente \
  -e SAFERPLACES_TOKEN=tuo-token \
  -- /percorso/assoluto/.venv/bin/python /percorso/assoluto/saferplaces_mcp.py

Verifica con /mcp dentro Claude Code: il server saferplaces deve comparire tra quelli connessi.

Deploy remoto (connettore per Claude.ai)

In modalità remota il server gira su un hosting raggiungibile via HTTPS e si collega a Claude.ai da Impostazioni → Connettori → Aggiungi connettore personalizzato, incollando l'URL. Funziona da browser e da mobile, senza nulla in esecuzione in locale.

Il trasporto HTTP si attiva con la variabile d'ambiente MCP_TRANSPORT=http (la porta si imposta con PORT, default 8000).

Opzione A — FastMCP Cloud

1. Carica questo repo su GitHub.

2. Su fastmcp.cloud collega il repo: la piattaforma rileva l'oggetto mcp in saferplaces_mcp.py e lo deploya.

3. Imposta SAFERPLACES_USER e SAFERPLACES_TOKEN tra le variabili d'ambiente del progetto.

4. Copia l'URL HTTPS generato e incollalo nei connettori di Claude.ai.

Opzione B — hosting generico (Cloud Run, Render, Railway, ...)

Comando di avvio:

MCP_TRANSPORT=http python saferplaces_mcp.py

Imposta SAFERPLACES_USER, SAFERPLACES_TOKEN e (se richiesto dalla piattaforma) PORT tra le variabili d'ambiente del servizio.

Sicurezza

⚠️ Un server remoto con le credenziali configurate permette a chiunque ne conosca l'URL di lanciare simulazioni con il tuo account e consumare la tua quota. Prima di esporlo su internet, proteggilo con l'autenticazione (FastMCP supporta bearer token e OAuth — vedi la documentazione di FastMCP, sezione Auth). Non committare mai le credenziali nel repo.

Risoluzione problemi

• ModuleNotFoundError: httpx / fastmcp → le dipendenze non sono installate nell'ambiente Python attivo: pip install -r requirements.txt.

• Errore all'avvio su variabili d'ambiente → SAFERPLACES_USER o SAFERPLACES_TOKEN non impostate.

• Errore di autenticazione dalle API → controlla USER_FIELD, TOKEN_FIELD e CREDENTIALS_INSIDE_INPUTS in cima a saferplaces_mcp.py: devono rispecchiare il body di una chiamata funzionante fatta a mano.

• Timeout su simulazioni lunghe → per untrim_run_and_wait alza timeout_seconds; il timeout delle singole richieste HTTP (300 s) si regola nella creazione del client httpx.