Documentazione MCP — Server Sarmate (setup, strumenti, FAQ)

Panoramica

Sarmate espone un server MCP (Model Context Protocol) che dà accesso al suo drive LaTeX a client IA esterni.

URL : https://mcp.sarmate.net/mcp
Transport : Streamable HTTP / SSE
Auth : Bearer token (Authorization: Bearer smt_xxx)
Piano : Tutti i piani (gratuito incluso), entro il limite della quota di compilazione — compilazione illimitata via MCP: Pro / Étab
Rate limit : 60 req/min/IP
Limite di token : 10 token attivi per account

Setup per client

Nota di sicurezza : Gli snippet qui sotto contengono smt_VOTRE_TOKEN — sostituiscilo manualmente con il suo token reale. Non digitare mai il suo token in un campo di una pagina pubblica (rischio di phishing, anche tramite un falso clone di questa pagina). Creare un account per generare un token.

Passo dopo passo — scelga la sua IA e segui le istruzioni adatte.

O andare direttamente alle schede per client

Claude Desktop (Mac / Windows / Linux)

Claude Desktop non parla HTTP in modo nativo. Bisogna usare il bridge mcp-remote (Node.js richiesto) che converte il trasporto stdio in HTTP.

File da modificare:

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Contenuto (unisci agli altri server MCP esistenti se ne hai):

{ "mcpServers": { "sarmate": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.sarmate.net/mcp", "--header", "Authorization: Bearer smt_VOTRE_TOKEN"] } } }

Chiudi completamente Claude Desktop (Cmd+Q su Mac) e riaprilo. Chiudere solo la finestra non basta.

Claude.ai (Web / iOS / Android) Presto

Claude Code (CLI) — passo passo completo

Recupera il suo token nel gestore file di Sarmate
In file_manager.php, clicca sull'icona MCP in alto a destra → Nuovo token. Facoltativamente, limita l'accesso a una sottocartella o a sola lettura. Copi il token (inizi con smt_) — viene mostrato una sola volta.
Apra Claude Code e chiedigli di configurare il server
In un terminale:
claude
Una volta aperta la sessione, incolla questo prompt con la config JSON e premi Invio — Claude Code si occupa del resto:
Aggiunga questo server MCP alla mia configurazione di Claude Code, per favore: { "mcpServers": { "sarmate": { "httpUrl": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }
Claude Code eseguirà il comando claude mcp add appropriato o modificherà direttamente il suo file di config. Per un utente avanzato che vuole saltare il passaggio conversazionale, il comando diretto equivalente: claude mcp add --transport http sarmate https://mcp.sarmate.net/mcp --header "Authorization: Bearer smt_TUO_TOKEN".
Ricarica la sessione affinché il server venga caricato
Nella sessione di Claude Code (ancora aperta) — digita:
/exit
Di nuovo nel terminale shell — riavvia con:
claude --continue
Riprende l'ultima sessione E ricarica la configurazione MCP. Senza ricaricamento, Claude Code non vede il nuovo server — l'elenco degli strumenti viene recuperato solo all'avvio.
Verifica la connessione

claude mcp list
Dovresti vedere sarmate ✓ Connected nell'elenco.
Prova lo strumento
Nella sessione, chiedi a Claude Code di interagire con il suo drive — ora ha accesso:
> Elenca i miei file .tex, apra main.tex, correggi gli errori e compila.
Claude Code concatenerà list_files → read_file → write_file → compile → get_compile_log in autonomia, finché il build non è pulito. Vedi ogni chiamata in tempo reale nel pannello.

Sicurezza : Non condividere mai il suo token e non committarlo in un repo. Se è trapelato, revocalo dal gestore file → MCP → Tokens (con un clic) e creane uno nuovo.

Cursor

Cursor parla HTTP in modo nativo (nessun bridge necessario). Modifichi:

~/.cursor/mcp.json (globale)
.cursor/mcp.json (per progetto)

{ "mcpServers": { "sarmate": { "url": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }

Possibile anche tramite Cursor Settings → MCP → Add Server.

Cline (VS Code)

In VS Code: sidebar Cline → MCP Servers → Configure MCP Servers, poi incolla:

{ "mcpServers": { "sarmate": { "url": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" }, "disabled": false } } }

Continue (VS Code)

Aggiunga questo blocco al suo ~/.continue/config.yaml:

mcpServers: - name: sarmate url: https://mcp.sarmate.net/mcp headers: Authorization: Bearer smt_VOTRE_TOKEN

ChatGPT (Developer Mode, beta)

Funzionalità beta. Plus / Pro = sola lettura; gli strumenti di scrittura sono riservati agli account Business / Enterprise / Edu.

Settings → Apps → Advanced settings → Developer mode
Create app
URL : https://mcp.sarmate.net/mcp
Transport : Streamable HTTP
Auth : Custom header → Authorization: Bearer smt_VOTRE_TOKEN

Gemini CLI

Metodo rapido (CLI già installato):

gemini mcp add --transport http --header "Authorization: Bearer smt_VOTRE_TOKEN" sarmate https://mcp.sarmate.net/mcp

Manualmente, in ~/.gemini/settings.json:

{ "mcpServers": { "sarmate": { "httpUrl": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }

Chiudi Gemini CLI (Ctrl+C) e riavvialo — settings.json viene letto solo all'avvio.

Le Chat (Mistral) — 🇫🇷 EU

Le Chat (l'LLM di Mistral, ospitato nell'UE) supporta i MCP connectors personalizzati direttamente dall'interfaccia web — nessun file di config da modificare.

Apra chat.mistral.ai — il pannello di sinistra è visibile per impostazione predefinita.
Intelligence → Connettori → Aggiunga un connettore.
Scheda Connettore MCP personalizzato, poi compila:
- Nome del connettore (titolo grande in alto — obbligatorio) : Sarmate
- Server del connettore : https://mcp.sarmate.net/mcp
- Descrizione (facoltativo) : Sarmate.net
- Metodo di autenticazione: Autenticazione tramite token API
- Nome dell'header : Authorization · Tipo di header : Bearer
- Valore dell'header : smt_VOTRE_TOKEN (solo il token — senza «Bearer» davanti)
Crei — il connettore è utilizzabile immediatamente, senza riavvio.

Disponibile su tutti i piani Le Chat (Free / Pro / Student). Sarmate × Le Chat = stack 100% europeo (Mistral France + Sarmate O2Switch / Ionos France), ideale per università e ricercatori con vincoli GDPR / sovranità.

Doc Mistral: docs.mistral.ai/le-chat/.../mcp-connectors

Altro client MCP

Configurazione generica per qualsiasi client MCP che supporti streamable HTTP + Bearer:

URL : https://mcp.sarmate.net/mcp
Transport : Streamable HTTP / SSE
Auth header : Authorization: Bearer smt_VOTRE_TOKEN

Per i client stdio-only (senza HTTP), usa mcp-remote come bridge:

npx -y mcp-remote https://mcp.sarmate.net/mcp --header "Authorization: Bearer smt_VOTRE_TOKEN"

Strumenti disponibili

11 strumenti disponibili. Tag: Lettura sicuro, sempre consentito — Scrittura crea uno snapshot prima della modifica — Compila consuma la sua quota di compilazione (tranne Pro/Etab).

read get_account_info

Piano, archiviazione, quota di compilazione, funzioni.

read list_files

Elencare il contenuto di una cartella (prima le cartelle, poi i file).

read read_file

Leggere il contenuto di un file di testo (1 MB max, rifiuta i file binari).

read search_files

Cercare nel drive (nome o contenuto). Filtrabile per sottocartella.

read get_compile_log

Ultimo log di compilazione di un .tex (status, error summary, excerpt).

write write_file

Sovrascrivere un file di testo esistente. Scrittura atomica. Snapshot prima.

write create_file

Creare un nuovo file. Fallisce se esiste già. Crei le cartelle mancanti.

write rename_file

Rinominare un file o una cartella (stessa cartella padre). Nessuno spostamento.

read list_history

Elencare gli snapshot disponibili (tutti o di un file specifico). 30 giorni di conservazione.

write restore_version

Ripristinare una versione precedente. La versione corrente viene salvata come snapshot prima del restore.

compile compile

Compila un file .tex O .md. Per .tex: xelatex / pdflatex / lualatex, dipendenze incluse. Per .md: Pandoc + xelatex one-shot, PDF scritto accanto al .md. Restituisce un estratto degli errori + l'URL del PDF. Permette all'IA di iterare da sola.

read read_pdf

Estrae il testo da un PDF (pdftotext, UTF-8). Intervallo di pagine opzionale. Indispensabile dopo compile(.md) affinché l'IA legga il proprio output e lo riassuma. PDF max 30 MB, testo max ~4 MB.

Flusso di lavoro Markdown

Un'IA ora può compilare Markdown senza installazione locale di Pandoc E analizzare il proprio PDF. Sequenza tipica:

// 1. Compile a .md to PDF
compile({ "path": "draft.md" })
// → { status: "success", mode: "markdown", pdf_path: "draft.pdf",
//      pdf_url: "https://user-content.sarmate.net/.../draft.pdf",
//      compilation_time_ms: 4231 }

// 2. Read the resulting PDF text for analysis
read_pdf({ "path": "draft.pdf" })
// → { text: "...", text_bytes: 23874, extract_ms: 412 }

// 3. If the .md compile fails, the response includes log_excerpt + hint
//    so the AI can fix the .md and retry.

Attenzione: nelle intestazioni YAML dei suoi .md, evita \usepackage{bm} o \boldsymbol{} — entrano in conflitto con unicode-math (caricato automaticamente da Pandoc + xelatex). Usa piuttosto \symbf{x} o \mathbf{x}.

Pagina completa sul flusso di lavoro Markdown: /markdown-to-latex.php

delete_file — disattivato intenzionalmente. L'eliminazione dei file passa dal suo file manager Sarmate (misura di sicurezza contro le allucinazioni dell'IA).

Sicurezza

Archiviazione bcrypt: token in hash, mai in chiaro.
Snapshot pre-scrittura: 30 giorni di conservazione. Ripristino tramite restore_version.
Path traversal bloccato: sanitize_rel + realpath check, impossibile leggere/scrivere fuori dal drive dell'utente.
Estensioni vietate: .php, .htaccess, .exe, .sh… (write_file/create_file lehnt ab).
Scope granulare: il token può essere limitato a una cartella e/o in sola lettura.
Audit log: ogni chiamata registrata (token_id, tool, params, status, IP, timestamp).
Revoca istantanea: il client IA viene disconnesso alla chiamata successiva.
Rate limit: 60 req/min/IP (nginx).

FAQ

Quanti token posso avere?

10 token attivi per account. I token revocati restano nella lista (per lo storico di audit) ma non contano più nel totale.

Qual è la quota di compilazione per piano?

La quota è in tempo di compilazione cumulato su una finestra scorrevole: Free 1 min/2 h (nessun accesso MCP), Perso 5 min/2 h, Pro/Etab illimitato. Il controllo è applicato sia lato editor web SIA lato MCP.

Cosa succede se creo un nuovo token con la stessa label?

La label è solo un indicatore di visualizzazione, non è univoca. Può avere più token con la stessa label (si distinguono per il loro prefisso mostrato nella UI).

Ho bisogno di una chiave API del fornitore LLM?

No. Usi il suo client IA esistente (il suo account Claude Desktop, Cursor, Gemini CLI…). Sarmate fornisce solo il token MCP per accedere al suo drive. Le due autenticazioni sono indipendenti.

Funziona con OAuth? E perché non con Claude.ai (web/mobile)?

Attualmente il server MCP di Sarmate supporta solo l'auth con Bearer token (token statici generati dalla UI). Funziona perfettamente con Claude Desktop, Claude Code, Cursor, Cline, Continue, Gemini CLI, ChatGPT (Developer Mode) e Le Chat.

Invece, Claude.ai (web/iOS/Android) richiede un'auth OAuth 2.1 completa con gli endpoint /authorize e /token. Se provi a connetterti, otterrai l'errore {"error":"not_found","path":"/authorize"}. OAuth è nella nostra roadmap (senza data). Nel frattempo, Claude Desktop e Claude Code ti offrono esattamente le stesse funzionalità MCP con la stessa IA di Anthropic.

I miei file vengono inviati all'IA?

Sì — non appena chiedi all'IA di leggere o compilare un file, il contenuto passa attraverso il fornitore di IA (Anthropic, OpenAI, Google…). Questi fornitori applicano le proprie politiche di conservazione e di utilizzo, da verificare dalla loro parte. Sarmate non aggiunge alcuna conservazione ulteriore oltre all'audit log (che contiene solo i metadati della chiamata, non il contenuto).

Posso self-hostare il server MCP?

No, il server MCP di Sarmate è centralizzato (accede al suo drive ospitato sui server di Sarmate). Se i suoi file sono in locale, esistono molti altri server MCP open source (filesystem, git, ecc.) nella directory ufficiale.

Come faccio a debuggare un errore di connessione?

Provi il token con un curl diretto (vedi sezione più in basso). Se restituisce 200, il problema è lato client (config non ricaricata, bridge mancante per Claude Desktop, URL sbagliato…). Se restituisce 401, il token è invalido o revocato — creane uno nuovo.

Esempi curl grezzi (debug)

Utile per verificare che il server e il suo token funzionino, indipendentemente dal client.

tools/list

curl -X POST https://mcp.sarmate.net/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer smt_VOTRE_TOKEN" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

tools/call (read_file)

Pronto a provare?

Crei un token in 30 secondi e copi lo snippet adatto al suo client.

Crei un account Torni alla presentazione

Documentazione tecnica MCP