Monitorare i tuoi server MCP in 5 minuti con MCPSonar e Docker

ai-integration - 20/07/2026

8 min read

Introduzione

Quando metti in produzione un server MCP (Model Context Protocol), sapere che il processo è "vivo" non basta. Un server può rispondere al ping ma avere l'handshake initialize rotto, dichiarare una spec version sbagliata o esporre tool che non rispondono più. I classici tool di uptime non se ne accorgono: vedono la porta aperta e ti dicono che è tutto ok.

MCPSonar nasce proprio per questo. È un tool self‑hosted, leggero, che fa health check protocol‑aware: parla davvero MCP. Esegue l'handshake initialize, registra la spec version dichiarata, elenca i tool, li chiama per verificare che rispondano davvero e valida il server contro le regole della versione del protocollo.

In questa guida lo installi con Docker in pochi minuti e configuri il monitoraggio del tuo primo server MCP.

Se non hai ancora chiaro cosa sia un client/server MCP, dai prima un'occhiata alla mia guida completa al Client MCP.

Perché il monitoring "generico" non basta per MCP

Un health check tradizionale (HTTP 200, ping TCP, docker healthcheck) risponde a una sola domanda: il processo è in esecuzione? Con MCP le cose che possono rompersi sono diverse e più subdole:

  1. Handshake fallito – il server risponde ma l'initialize va in errore o restituisce una spec version incompatibile con i tuoi client.
  2. Tool spariti o rotti – la tools/list cambia dopo un deploy, oppure un tool è ancora elencato ma va in timeout quando lo chiami.
  3. Latenza degradata – il server risponde, ma così lentamente da rendere inutilizzabile l'esperienza dell'agente.
  4. Transport instabile – SSE che droppa la connessione, stdio che non parte.

MCPSonar controlla tutti questi livelli e ti mostra uptime, storico della latenza e stato dei singoli tool in una dashboard.

Prerequisiti

  • Docker e Docker Compose installati
  • (Opzionale) Node.js se vuoi monitorare server MCP di tipo stdio lanciati via npx
  • Almeno un server MCP da monitorare — anche uno di test va benissimo

Passo 1 — Installazione con Docker

Clona il repository e avvia lo stack:

git clone https://github.com/alefra93/MCPSonar.git
cd MCPSonar
docker compose up -d

Il database SQLite viene persistito in un volume dedicato (mcpsonar-data), quindi la configurazione e lo storico sopravvivono ai riavvii del container.

A questo punto la dashboard è raggiungibile su:

http://localhost:8675

Al primo accesso ti viene chiesto di creare un account admin (password di almeno 8 caratteri). Fatto questo, sei dentro.

Preferisci senza Docker? Puoi avviarlo anche da sorgente con Python 3.11+:

python -m venv .venv
.venv\Scripts\Activate.ps1   # su Windows; su Linux/Mac: source .venv/bin/activate
pip install -e .
mcpsonar run

In questo caso la dashboard è su http://127.0.0.1:8675.

Passo 2 — Aggiungere il primo server MCP

Puoi aggiungere un server direttamente dalla dashboard (bottone Add server) oppure descriverlo in un file YAML e caricarlo al primo avvio. Il secondo approccio è ottimo perché la configurazione diventa versionabile in git.

Ecco un esempio di config.yaml per un server MCP esposto via HTTP:

servers:
  my-http-server:
    url: "https://example.com/mcp"
    transport: "http"          # http | sse | stdio
    headers:
      Authorization: "Bearer <token>"
    check_interval_seconds: 60
    tools_to_test:
      - ping
      - name: search
        arguments: { query: "healthcheck" }
    thresholds:
      latency_degraded_ms: 2000
      latency_down_ms: 10000

Analizziamo i campi che contano:

  • url e transport – dove sta il server e con quale protocollo di trasporto parlare.
  • headers – header di autenticazione per i server protetti (es. un Bearer token).
  • check_interval_seconds – ogni quanto eseguire il check.
  • tools_to_test – la parte più interessante: qui elenchi i tool che MCPSonar deve chiamare davvero. Puoi passare solo il nome (ping) o nome + argomenti per una chiamata realistica.
  • thresholds – le soglie di latenza oltre le quali lo stato passa a degraded o down.

Per caricare il file al primo avvio:

mcpsonar run --config config.yaml

Passo 3 — I tre transport: http, SSE e stdio

MCP supporta transport diversi e MCPSonar li gestisce tutti. La differenza principale in configurazione:

HTTP / SSE — server raggiungibili tramite URL, con header di auth opzionali. La config è quella vista sopra; per SSE basta cambiare transport: "sse".

stdio — server locali che MCPSonar lancia come processo a ogni check. Utile per i tanti server MCP distribuiti come pacchetti npm o Python:

servers:
  stdio-server:
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-everything"]
    tools_to_test:
      - name: echo
        arguments: { message: "healthcheck" }

Con stdio serve l'ambiente adatto nel container/host: Node per npx, Python per uvx.

Il server @modelcontextprotocol/server-everything è perfetto per una prova: espone tool di esempio come echo senza bisogno di configurare nulla di reale.

Passo 4 — Leggere la dashboard

Una volta configurati i server, la dashboard ti dà a colpo d'occhio:

  • Stato di ogni server: up, degraded o down, basato su handshake, tool ed eventuali soglie di latenza.
  • Uptime % e grafico dello storico della latenza.
  • Spec version dichiarata dal server durante l'initialize.
  • Elenco dei tool esposti e l'esito dei test‑call configurati.

Da qui puoi anche mettere in pausa un server (utile durante un deploy per evitare falsi allarmi), modificarne la configurazione o lanciare un check on‑demand senza aspettare l'intervallo schedulato.

Passo 5 — Integrare notifiche e metriche

Monitorare senza essere avvisati serve a poco. MCPSonar espone diversi adapter di integrazione, da aggiungere nella config del singolo server:

servers:
  my-http-server:
    # ...resto della config...
    webhooks:
      - type: uptime_kuma
        push_url: "https://kuma.example.com/api/push/xyz"
      - type: generic
        url: "https://hooks.example.com/webhook"
        on: ["down", "degraded"]
  • Uptime Kuma – MCPSonar fa una GET di push all'URL configurato, così puoi centralizzare lo stato nella tua istanza Kuma.
  • Webhook generico – POST del payload CheckEvent in JSON, con filtro sugli stati (on: ["down", "degraded"]) per non farti spammare a ogni check ok.
  • Prometheus – le metriche sono esposte sull'endpoint /metrics, pronte da scrapare e mandare su Grafana.

Quest'ultimo punto è quello che chiude il cerchio per un setup di observability serio: dashboard MCPSonar per la vista MCP‑specifica, Prometheus + Grafana per storico e alerting insieme al resto della tua infrastruttura.

Conclusione

In pochi minuti hai un monitoraggio che capisce davvero MCP: non ti dice solo "il processo è vivo", ma "l'handshake funziona, la spec version è quella giusta, i tool rispondono e la latenza è nei limiti". Che è esattamente ciò che ti serve sapere prima che se ne accorgano i tuoi agenti (o i tuoi utenti).

Da qui puoi:

  • aggiungere tutti i tuoi server MCP in un unico config.yaml versionato;
  • collegare le notifiche verso lo stack che già usi;
  • scalare il monitoraggio man mano che aggiungi tool e transport.

Il progetto è open source: se ti è utile, dai un'occhiata al repository su GitHub, lascia una stella e apri pure issue o PR.

Per approfondire, ho scritto anche sul perché l'uptime classico non basta per MCP, sull'anatomia dell'handshake MCP e sul confronto tra i transport http, SSE e stdio — sono il cuore di come MCPSonar decide se un server è davvero sano.