Documentation MCP — Serveur Sarmate (setup, outils, FAQ)

Vue d'ensemble

Sarmate expose un serveur MCP (Model Context Protocol) qui donne accès à votre drive LaTeX à des clients IA externes.

URL : https://mcp.sarmate.net/mcp
Transport : Streamable HTTP / SSE
Auth : Bearer token (Authorization: Bearer smt_xxx)
Plan : Tous les plans (gratuit inclus), dans la limite du quota de compilation — compilation illimitée via MCP : Pro / Étab
Rate limit : 60 req/min/IP
Limite de tokens : 10 tokens actifs par compte

Setup par client

Note de sécurité : Les snippets ci-dessous contiennent smt_VOTRE_TOKEN — remplacez-le manuellement par votre vrai token. Ne saisissez jamais votre token dans un champ d'une page publique (risque de phishing, y compris via un faux clone de cette page). Créer un compte pour générer un token.

Guidé pas à pas — choisissez votre IA et suivez les instructions adaptées.

Ou aller directement aux onglets par client

Claude Desktop (Mac / Windows / Linux)

Claude Desktop ne parle pas HTTP nativement. Il faut utiliser le bridge mcp-remote (Node.js requis) qui convertit le transport stdio en HTTP.

Fichier à éditer :

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

Contenu (fusionner avec les autres serveurs MCP existants si vous en avez) :

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

Quittez complètement Claude Desktop (Cmd+Q sur Mac) puis relancez-le. Une simple fermeture de fenêtre ne suffit pas.

Claude.ai (Web / iOS / Android) Bientôt

Claude Code (CLI) — pas-à-pas complet

Récupérez votre token dans le gestionnaire de fichiers Sarmate
Dans file_manager.php, cliquez sur l'icône MCP en haut à droite → Nouveau token. Optionnellement, restreignez l'accès à un sous-dossier ou en lecture seule. Copiez le token (commence par smt_) — il n'est affiché qu'une seule fois.
Ouvrez Claude Code et demandez-lui de configurer le serveur
Dans un terminal :
claude
Une fois la session ouverte, collez ce prompt avec la config JSON et appuyez sur Entrée — Claude Code se charge du reste :
Ajoute ce serveur MCP à ma configuration Claude Code stp : { "mcpServers": { "sarmate": { "httpUrl": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }
Claude Code exécutera la commande claude mcp add appropriée ou éditera directement son fichier de config. Pour un utilisateur avancé qui veut sauter le passage conversationnel, la commande directe équivalente : claude mcp add --transport http sarmate https://mcp.sarmate.net/mcp --header "Authorization: Bearer smt_VOTRE_TOKEN".
Rechargez la session pour que le serveur soit chargé
Dans la session Claude Code (encore ouverte) — tapez :
/exit
De retour dans le terminal shell — relancez avec :
claude --continue
Reprend la dernière session ET recharge la configuration MCP. Sans rechargement, Claude Code ne voit pas le nouveau serveur — la liste des outils n'est récupérée qu'au démarrage.
Vérifiez la connexion

claude mcp list
Vous devriez voir sarmate ✓ Connected dans la liste.
Testez l'outil
Dans la session, demandez à Claude Code d'interagir avec votre drive — il y a désormais accès :
> Liste mes fichiers .tex, ouvre main.tex, corrige les erreurs et compile.
Claude Code va enchaîner list_files → read_file → write_file → compile → get_compile_log en autonomie, jusqu'à ce que le build soit propre. Vous voyez chaque appel en temps réel dans le panneau.

Sécurité : Ne partagez jamais votre token et ne le commitez pas dans un repo. S'il a fuité, révoquez-le depuis le gestionnaire de fichiers → MCP → Tokens (en un clic) et créez-en un nouveau.

Cursor

Cursor parle HTTP nativement (pas de bridge nécessaire). Éditez :

~/.cursor/mcp.json (global)
.cursor/mcp.json (par projet)

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

Aussi possible via Cursor Settings → MCP → Add Server.

Cline (VS Code)

Dans VS Code : sidebar Cline → MCP Servers → Configure MCP Servers, puis collez :

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

Continue (VS Code)

Ajoutez ce bloc à votre ~/.continue/config.yaml :

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

ChatGPT (Developer Mode, beta)

Fonctionnalité beta. Plus / Pro = lecture seule ; les outils en écriture sont réservés aux comptes 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

Méthode rapide (CLI déjà installé) :

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

Manuellement, dans ~/.gemini/settings.json :

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

Quittez Gemini CLI (Ctrl+C) puis relancez-le — settings.json est lu seulement au démarrage.

Le Chat (Mistral) — 🇫🇷 EU

Le Chat (le LLM de Mistral, hébergé dans l'UE) supporte les MCP connectors personnalisés directement depuis l'interface web — aucun fichier de config à éditer.

Ouvrez chat.mistral.ai — le panneau de gauche est visible par défaut.
Intelligence → Connecteurs → Ajouter un connecteur.
Onglet Connecteur MCP personnalisé, puis renseignez :
- Nom du connecteur (grand titre en haut — obligatoire) : Sarmate
- Serveur du connecteur : https://mcp.sarmate.net/mcp
- Description (facultatif) : Sarmate.net
- Méthode d'authentification : Authentification par token API
- Nom de l'en-tête : Authorization · Type d'en-tête : Bearer
- Valeur de l'en-tête : smt_VOTRE_TOKEN (le token seul — sans « Bearer » devant)
Créer — le connecteur est utilisable immédiatement, sans redémarrage.

Disponible sur tous les plans Le Chat (Free / Pro / Student). Sarmate × Le Chat = pile 100% européenne (Mistral France + Sarmate O2Switch / Ionos France), idéal pour facs et chercheurs avec contraintes RGPD / souveraineté.

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

Autre client MCP

Configuration générique pour tout client MCP supportant streamable HTTP + Bearer :

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

Pour les clients stdio-only (pas de HTTP), utilisez mcp-remote comme bridge :

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

Outils disponibles

11 outils disponibles. Tags : Lecture sûr, toujours autorisé — Écriture crée un snapshot avant modification — Compile consomme votre quota de compilation (sauf Pro/Etab).

read get_account_info

Plan, stockage, quota compile, features.

read list_files

Lister le contenu d'un dossier (dossiers d'abord, puis fichiers).

read read_file

Lire le contenu d'un fichier texte (1 MB max, refuse les binaires).

read search_files

Chercher dans le drive (nom ou contenu). Filtrable par sous-dossier.

read get_compile_log

Dernier log de compilation d'un .tex (status, error summary, excerpt).

write write_file

Écraser un fichier texte existant. Écriture atomique. Snapshot avant.

write create_file

Créer un nouveau fichier. Échoue s'il existe déjà. Crée les dossiers manquants.

write rename_file

Renommer un fichier ou dossier (même dossier parent). Pas de déplacement.

read list_history

Lister les snapshots disponibles (tous ou d'un fichier précis). 30 jours de rétention.

write restore_version

Restaurer une version précédente. La version courante est snapshotée avant restore.

compile compile

Compiler une .tex OU une .md. Pour .tex : xelatex / pdflatex / lualatex, dépendances bundlées. Pour .md : Pandoc + xelatex one-shot, PDF écrit à côté du .md. Extrait d'erreurs + URL PDF retournés. Permet à l'IA d'itérer seule.

read read_pdf

Extraire le texte d'un PDF (pdftotext, UTF-8). Plage de pages optionnelle. Indispensable après compile(.md) pour que l'IA lise son propre output et le résume. PDF max 30 Mo, texte max ~4 Mo.

Workflow Markdown

Une IA peut maintenant compiler du Markdown sans installation locale de Pandoc ET analyser son propre PDF. Séquence type :

// 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.

Attention : dans les en-têtes YAML de vos .md, évitez \usepackage{bm} ou \boldsymbol{} — ils entrent en conflit avec unicode-math (auto-chargé par Pandoc + xelatex). Utilisez plutôt \symbf{x} ou \mathbf{x}.

Page complète sur le workflow Markdown : /markdown-to-latex.php

delete_file — désactivé intentionnellement. La suppression de fichiers passe par votre file manager Sarmate (mesure de sécurité contre les hallucinations de l'IA).

Sécurité

Stockage bcrypt: tokens en hash, jamais en clair.
Snapshots pré-écriture: 30 jours de rétention. Restauration via restore_version.
Path traversal bloqué: sanitize_rel + realpath check, lecture/écriture hors du drive user impossible.
Extensions interdites: .php, .htaccess, .exe, .sh… (write_file/create_file lehnt ab).
Scope granulaire: token limitable à un dossier et/ou en lecture seule.
Audit log: chaque appel enregistré (token_id, tool, params, status, IP, timestamp).
Révocation instantanée: le client IA est déconnecté au prochain appel.
Rate limit: 60 req/min/IP (nginx).

FAQ

Combien de tokens puis-je avoir ?

10 tokens actifs par compte. Les tokens révoqués restent dans la liste (pour l'historique d'audit) mais ne comptent plus dans le total.

Quel est le quota de compilation par plan ?

Le quota est en temps de compilation cumulé sur une fenêtre glissante : Free 1 min/2 h (pas d'accès MCP), Perso 5 min/2 h, Pro/Etab illimité. Le check est appliqué côté éditeur web ET côté MCP.

Que se passe-t-il si je crée un nouveau token avec le même label ?

Le label est juste un indicateur d'affichage, pas unique. Vous pouvez avoir plusieurs tokens avec le même label (ils sont distingués par leur préfixe affiché dans l'UI).

Ai-je besoin d'une clé API du fournisseur LLM ?

Non. Vous utilisez votre client IA existant (votre compte Claude Desktop, Cursor, Gemini CLI…). Sarmate fournit uniquement le token MCP pour accéder à votre drive. Les deux authentifications sont indépendantes.

Est-ce que ça fonctionne en OAuth ? Et pourquoi pas avec Claude.ai (web/mobile) ?

Actuellement le serveur MCP Sarmate ne supporte que l'auth Bearer token (tokens statiques générés via l'UI). Cela fonctionne parfaitement avec Claude Desktop, Claude Code, Cursor, Cline, Continue, Gemini CLI, ChatGPT (Developer Mode) et Le Chat.

En revanche, Claude.ai (web/iOS/Android) exige une auth OAuth 2.1 complète avec les endpoints /authorize et /token. Si vous tentez de vous connecter, vous obtiendrez l'erreur {"error":"not_found","path":"/authorize"}. OAuth est dans notre roadmap (sans date). En attendant, Claude Desktop et Claude Code vous offrent exactement les mêmes capacités MCP avec la même IA Anthropic.

Mes fichiers sont-ils envoyés à l'IA ?

Oui — dès que vous demandez à l'IA de lire ou compiler un fichier, le contenu transite par le fournisseur IA (Anthropic, OpenAI, Google…). Ces fournisseurs appliquent leurs propres politiques de rétention et d'usage, à vérifier de leur côté. Sarmate n'ajoute pas de rétention supplémentaire au-delà de l'audit log (qui ne contient que les métadonnées de l'appel, pas le contenu).

Puis-je self-hoster le serveur MCP ?

Non, le serveur MCP Sarmate est centralisé (il accède à votre drive hébergé sur les serveurs Sarmate). Si vos fichiers sont en local, il existe beaucoup d'autres serveurs MCP open source (filesystem, git, etc.) dans le directory officiel.

Comment débugger une erreur de connexion ?

Testez le token avec un curl direct (voir section plus bas). S'il retourne 200, le problème est côté client (config pas rechargée, bridge manquant pour Claude Desktop, mauvaise URL…). S'il retourne 401, le token est invalide ou révoqué — créez-en un nouveau.

Exemples curl bruts (debug)

Utile pour valider que le serveur et votre token fonctionnent, indépendamment du 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)

Prêt à essayer ?

Créez un token en 30 secondes et copiez le snippet adapté à votre client.

Créer un compte Retour à la présentation

Documentation technique MCP