A4X

Guida creazione server MCP per documenti aziendali

6 minuti

Guida creazione server MCP

Un server MCP (Model Context Protocol) permette a Claude di elencare tutti i file e le cartelle condivise in azienda e leggerne il contenuto (testo semplice, PDF, DOCX, XLSX).

Info

In questa guida sono stati inseriti dei link, riconoscibili dal corsivo (es. server MCP), che spiegano meglio alcune sezioni per renderla più comprensibile.

Requisiti

  • Server Linux con Python 3.10 o superiore
  • Dominio che punta all’IP pubblico del server (es. mcp.tuodominio.it)
  • Reverse proxy HTTPS già configurato (Nginx, Traefik, HAProxy o equivalente)
  • Accesso amministrativo al server
  • Cartella condivisa contenente i documenti aziendali da rendere disponibili a Claude
  • A questa pagina è possibile recuperare il codice Python del server MCP

Info

In questa configurazione il server MCP non gestisce direttamente il certificato SSL. La terminazione HTTPS viene effettuata dal reverse proxy che espone il servizio su Internet.

Configurazione iniziale

Installare le dipendenze di sistema

Aggiornare i repository e installare Python e gli strumenti necessari:

apt update && apt install python3 python3-pip python3-venv acl -y

Le librerie installate servono rispettivamente per:

  • python3: interprete Python
  • python3-pip: gestore pacchetti Python
  • python3-venv: creazione di ambienti virtuali Python
  • acl: gestione dei permessi avanzati tramite ACL

Creare una cartella per il progetto

Creare una cartella dedicata al server MCP:

mkdir -p /opt/mcp-fileserver
cd /opt/mcp-fileserver

Creare un ambiente virtuale Python

Un ambiente virtuale Python permette di isolare le librerie del progetto dal resto del sistema operativo.

python3 -m venv venv
source venv/bin/activate

Dopo l’attivazione comparirà normalmente il prefisso (venv) all’inizio della riga di comando.

Installare le librerie Python

Installare le dipendenze richieste dal server:

pip install "mcp>=1.6,<2" uvicorn pymupdf python-docx openpyxl watchdog xlrd

Queste librerie permettono al server di:

  • comunicare tramite protocollo MCP
  • esporre un server HTTP
  • leggere file PDF
  • leggere documenti Word
  • leggere fogli Excel
  • monitorare modifiche a file e cartelle

Salvare il codice del server

Creare il file che conterrà il codice Python:

nano /opt/mcp-fileserver/server.py

Incollare il contenuto disponibile a questa pagina.

Salvare e chiudere l’editor (Ctrl+X, poi Y, poi Invio).

Verificare il codice

Prima di procedere è consigliabile verificare che non siano presenti errori sintattici:

python3 -c "import ast; ast.parse(open('server.py').read()); print('OK')"

Se tutto è corretto verrà mostrato:

OK

Creazione dell’utente dedicato

Per motivi di sicurezza il server MCP non deve essere eseguito come utente root.

Creare quindi un utente di sistema dedicato:

useradd --system --no-create-home mcp-user

L’utente mcp-user verrà utilizzato esclusivamente per eseguire il servizio MCP.

File dei segreti

I dati sensibili non devono essere inseriti direttamente nel codice Python.

Creare una cartella dedicata alla configurazione:

mkdir -p /etc/mcp-fileserver
nano /etc/mcp-fileserver/secrets

Generare il client secret

Il client secret viene utilizzato da Claude per autenticarsi verso il server MCP.

Generarlo con:

python3 -c "import secrets; print(secrets.token_hex(32))"

Verrà prodotto un valore simile a:

4db4f0f9cb6e0b8f5d3a7f8f6f6b5e1d8a3f2b5e7f1c4d9e2a7b6c8d9f0a1b2

Conservarlo perché servirà durante la configurazione di Claude.

Configurare il file secrets

Inserire i valori nel file:

MCP_BASE_DIR=/percorso/cartella/condivisa
MCP_CLIENT_ID=mcp-aziendale
MCP_CLIENT_SECRET=incolla-qui-il-valore-generato
MCP_ALLOWED_HOST=mcp.tuodominio.it
MCP_DB_PATH=/opt/mcp-fileserver/mcp.db
MCP_PORT=8000

Descrizione delle variabili:

VariabileDescrizione
MCP_BASE_DIRCartella che contiene i documenti condivisi
MCP_CLIENT_IDIdentificativo OAuth utilizzato da Claude
MCP_CLIENT_SECRETSegreto OAuth utilizzato da Claude
MCP_ALLOWED_HOSTNome DNS pubblico del server
MCP_DB_PATHDatabase locale utilizzato dal server
MCP_PORTPorta TCP sulla quale il server rimane in ascolto

È possibile definire anche:

MCP_TOKEN_EXPIRY=86400

Questa variabile controlla la durata dei token di autenticazione in secondi.

Se omessa viene utilizzato il valore predefinito di 86400 secondi (24 ore).

Proteggere il file dei segreti

Limitare l’accesso al file:

chmod 640 /etc/mcp-fileserver/secrets
chown root:mcp-user /etc/mcp-fileserver/secrets

In questo modo solo root e il servizio MCP potranno leggerne il contenuto.

Permessi di accesso ai documenti

Il server deve poter leggere la cartella condivisa ma non modificarla.

Permessi sulla cartella del progetto

Assegnare la proprietà del progetto all’utente dedicato:

chown -R mcp-user:mcp-user /opt/mcp-fileserver

Accesso ai documenti aziendali

Concedere all’utente del servizio l’accesso in sola lettura:

setfacl -R -m u:mcp-user:rX /percorso/cartella/condivisa

Cos’è una ACL

Info

Il server potrà leggere file e cartelle ma non modificarli o eliminarli.

Configurazione come servizio systemd

Systemd permette di eseguire automaticamente il server all’avvio del sistema e di riavviarlo in caso di errore.

Creare il file di servizio

nano /etc/systemd/system/mcp-fileserver.service

Contenuto:

[Unit]
Description=MCP File Server Aziendale
After=network.target
 
[Service]
ExecStart=/opt/mcp-fileserver/venv/bin/python /opt/mcp-fileserver/server.py
Restart=always
User=mcp-user
WorkingDirectory=/opt/mcp-fileserver
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=/etc/mcp-fileserver/secrets
 
# Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/mcp-fileserver
ProtectHome=true
 
[Install]
WantedBy=multi-user.target

Significato delle opzioni di sicurezza

Le opzioni presenti nella sezione Hardening aumentano la sicurezza del servizio:

  • NoNewPrivileges=true impedisce l’acquisizione di privilegi aggiuntivi
  • PrivateTmp=true fornisce una directory temporanea isolata
  • ProtectSystem=strict rende il sistema operativo in sola lettura
  • ReadWritePaths=/opt/mcp-fileserver permette la scrittura solo nella cartella del progetto
  • ProtectHome=true impedisce l’accesso alle home degli utenti

Approfondimento hardening systemd

Avviare il servizio

Ricaricare la configurazione di systemd:

systemctl daemon-reload

Abilitare il servizio all’avvio:

systemctl enable mcp-fileserver

Avviare il servizio:

systemctl start mcp-fileserver

Verificare che il servizio sia attivo

systemctl status mcp-fileserver

Lo stato deve risultare:

active (running)

Consultare i log

Per visualizzare i log in tempo reale:

journalctl -u mcp-fileserver -f

Durante il primo avvio dovrebbero comparire messaggi simili a:

BASE_DIR=/percorso/cartella/condivisa ...
Token attivi ricaricati dal DB: 0
Indicizzazione iniziale avviata...
Watcher avviato su ...

Configurazione del reverse proxy

Il server MCP rimane in ascolto sulla porta configurata tramite MCP_PORT (normalmente 8000).

Il reverse proxy riceve le connessioni HTTPS provenienti da Internet e le inoltra al server MCP.

Schema semplificato:

Claude
   │
 HTTPS
   │
mcp.tuodominio.it
   │
Reverse Proxy
   │
HTTP localhost:8000
   │
Server MCP

Cos’è un reverse proxy

Configurazione in Claude Team

Per l’amministratore

  1. Vai su https://claude.ai
  2. Apri Organization settings
  3. Vai nella sezione Connectors
  4. Clicca Add custom connector
  5. Compila i campi:
    • Name: File Server Aziendale
    • URL: https://mcp.tuodominio.it
  6. Apri Advanced settings
    • OAuth Client ID: mcp-aziendale
    • OAuth Client Secret: il valore di MCP_CLIENT_SECRET
  7. Clicca Add

Per i dipendenti

Ogni membro del team deve:

  1. Aprire Settings
  2. Entrare in Connectors
  3. Individuare il connector aziendale
  4. Cliccare Connect

Dopo la prima autorizzazione Claude potrà accedere ai documenti condivisi.

Manutenzione

Verificare il numero di file indicizzati

journalctl -u mcp-fileserver | grep "Indicizzazione completata"

Forzare una re-indicizzazione completa

Se la struttura documentale cambia radicalmente è possibile ricostruire l’indice:

rm /opt/mcp-fileserver/mcp.db
systemctl restart mcp-fileserver

Al riavvio verrà eseguita una nuova scansione completa.

Aggiornare le librerie Python

Attivare l’ambiente virtuale:

source /opt/mcp-fileserver/venv/bin/activate

Aggiornare le dipendenze:

pip install --upgrade "mcp>=1.6,<2" uvicorn pymupdf python-docx openpyxl watchdog xlrd

Riavviare il servizio:

systemctl restart mcp-fileserver

Riavviare il server MCP

In caso di manutenzione ordinaria:

systemctl restart mcp-fileserver

Arrestare il servizio

systemctl stop mcp-fileserver

Disabilitare l’avvio automatico

systemctl disable mcp-fileserver