Sarmate.net Sarmate.net
Log in Sign up
Home Features Pricing Documentation Contact
Log in Sign up
Sarmate × MCP Documentation

MCP Technical Documentation

Full setup snippets, description of all 11 tools, frequently asked questions.

Overview

Sarmate exposes an MCP server (Model Context Protocol) that gives external AI clients access to your LaTeX drive.

  • URL : https://mcp.sarmate.net/mcp
  • Transport : Streamable HTTP / SSE
  • Auth : Bearer token (Authorization: Bearer smt_xxx)
  • Plan : All plans (free included), within the compilation quota — unlimited compilation via MCP: Pro / Etab
  • Rate limit : 60 req/min/IP
  • Token limit : 10 active tokens per account

Per-client setup

Security note : The snippets below contain smt_VOTRE_TOKEN — replace it manually with your real token. Never type your token into a form on a public page (phishing risk, including via fake clones of this page). Create an account to generate a token.

Step-by-step — choose your AI and follow the matching instructions.

Or jump directly to per-client tabs

Claude Desktop (Mac / Windows / Linux)

Claude Desktop does not speak HTTP natively. You need the mcp-remote bridge (requires Node.js) which converts stdio transport to HTTP.

File to edit:

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

Content (merge with other existing MCP servers if any):

{ "mcpServers": { "sarmate": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.sarmate.net/mcp", "--header", "Authorization: Bearer smt_VOTRE_TOKEN"] } } }
Fully quit Claude Desktop (Cmd+Q on Mac) and reopen it. Just closing the window is not enough.

Claude.ai (Web / iOS / Android) Coming soon

Claude.ai (Web/iOS/Android) is not supported yet.

Unlike Claude Desktop and Claude Code, Claude.ai requires full OAuth 2.1 authentication, which the Sarmate MCP server has not implemented yet (Bearer token auth only for now). OAuth is on our roadmap.

In the meantime, Claude Desktop or Claude Code give you exactly the same MCP capabilities, with the same Anthropic AI behind.

Claude Code (CLI) — full step-by-step

  1. Get your token from the Sarmate file manager
    In file_manager.php, click the MCP icon top-right → New token. Optionally restrict access to a subfolder or set read-only. Copy the token (starts with smt_) — it's shown only once.
  2. Open Claude Code and ask it to configure the server
    In a terminal:
    claude
    Once the session is open, paste this prompt with the JSON config and press Enter — Claude Code handles the rest:
    Please add this MCP server to my Claude Code config: { "mcpServers": { "sarmate": { "httpUrl": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }
    Claude Code will run the appropriate claude mcp add command or edit its config file directly. For advanced users who want to skip the conversational step, the equivalent direct command: claude mcp add --transport http sarmate https://mcp.sarmate.net/mcp --header "Authorization: Bearer smt_VOTRE_TOKEN".
  3. Reload the session so the server is loaded
    Inside the Claude Code session (still open) — type:
    /exit
    Back in the shell terminal — restart with:
    claude --continue
    Resumes the previous session AND reloads the MCP config. Without a reload, Claude Code won't see the new server — tool lists are fetched only on startup.
  4. Check the connection
    claude mcp list
    You should see sarmate ✓ Connected in the list.
  5. Test the tool
    In the session, ask Claude Code to interact with your drive — it now has access:
    > List my .tex files, open main.tex, fix the errors and compile it.
    Claude Code will chain list_files → read_file → write_file → compile → get_compile_log autonomously, until the build is clean. You see each call in real time in the side panel.
Security : Never share your token or commit it to a repo. If leaked, revoke it from the file manager → MCP → Tokens (one click) and generate a new one.

Cursor

Cursor speaks HTTP natively (no bridge needed). Edit:

  • ~/.cursor/mcp.json (global)
  • .cursor/mcp.json (per project)
{ "mcpServers": { "sarmate": { "url": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }

Also possible via Cursor Settings → MCP → Add Server.

Cline (VS Code)

In VS Code: Cline sidebar → MCP Servers → Configure MCP Servers, then paste:

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

Continue (VS Code)

Add this block to your ~/.continue/config.yaml:

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

ChatGPT (Developer Mode, beta)

Beta feature. Plus / Pro = read-only; write tools restricted to Business / Enterprise / Edu accounts.

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

Gemini CLI

Quick method (CLI already installed):

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

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

{ "mcpServers": { "sarmate": { "httpUrl": "https://mcp.sarmate.net/mcp", "headers": { "Authorization": "Bearer smt_VOTRE_TOKEN" } } } }
Quit Gemini CLI (Ctrl+C) and restart it — settings.json is read only at startup.

Le Chat (Mistral) — 🇫🇷 EU

Le Chat (Mistral's LLM, EU-hosted) supports custom MCP connectors directly from the web UI — no config file to edit.

  1. Open chat.mistral.ai — the left-hand sidebar is visible by default.
  2. Intelligence → Connectors → + Add Connector.
  3. Select the Custom MCP Connector tab, then fill in:
    • Connector name (large title at top — required) : Sarmate
    • Connector server : https://mcp.sarmate.net/mcp
    • Description (optional) : Sarmate.net
    • Authentication method: API token authentication
    • Header name : Authorization · Header type : Bearer
    • Header value : smt_VOTRE_TOKEN (token only — no "Bearer" prefix)
  4. Create — the connector is usable immediately, no restart needed.

Available on all Le Chat plans (Free / Pro / Student). Sarmate × Le Chat = fully European stack (Mistral France + Sarmate O2Switch / Ionos France), ideal for universities and researchers with GDPR / sovereignty requirements.

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

Other MCP client

Generic configuration for any MCP client supporting streamable HTTP + Bearer:

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

For stdio-only clients (no HTTP), use mcp-remote as a bridge:

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

Available tools

11 tools available. Tags: Read safe, always allowed — Write creates a snapshot before edit — Compile consumes your compile quota (except Pro/Etab).

read get_account_info
Plan, storage, compile quota, features.
read list_files
List a folder contents (folders first, then files).
read read_file
Read a text file content (1 MB max, rejects binary files).
read search_files
Search the drive (name or content). Filterable by subfolder.
read get_compile_log
Latest compile log for a .tex (status, error summary, excerpt).
write write_file
Overwrite an existing text file. Atomic write. Snapshot before.
write create_file
Create a new file. Fails if it exists. Creates missing folders.
write rename_file
Rename a file or folder (same parent folder). No move across folders.
read list_history
List available snapshots (all or for a specific file). 30-day retention.
write restore_version
Restore a previous version. Current version is snapshotted before restore.
compile compile
Compile a .tex OR .md file. For .tex: xelatex / pdflatex / lualatex, dependencies bundled. For .md: Pandoc + xelatex one-shot, PDF written next to the .md. Error excerpt + PDF URL returned. Lets the AI iterate autonomously.
read read_pdf
Extract text from a PDF file (pdftotext, UTF-8). Optional page range. Essential after compile(.md) so the AI reads its own output and summarises it. PDF max 30 MB, text max ~4 MB.

Markdown workflow

An AI can now compile Markdown without a local Pandoc install AND analyse its own PDF. Typical call sequence: 

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

Caveat: in the YAML headers of your .md, avoid \usepackage{bm} or \boldsymbol{} — they conflict with unicode-math (auto-loaded by Pandoc + xelatex). Use \symbf{x} or \mathbf{x} instead.

Full page on the Markdown workflow: /markdown-to-latex.php

delete_file — intentionally disabled. File deletions go through your Sarmate file manager (safety measure against AI hallucinations).

Security

  • Bcrypt storage: tokens hashed, never plaintext.
  • Pre-edit snapshots: 30-day retention. Restore via restore_version.
  • Path traversal blocked: sanitize_rel + realpath check, read/write outside the user drive impossible.
  • Forbidden extensions: .php, .htaccess, .exe, .sh… (write_file/create_file lehnt ab).
  • Granular scope: token can be limited to a folder and/or read-only.
  • Audit log: every call logged (token_id, tool, params, status, IP, timestamp).
  • Instant revocation: AI client is disconnected on next call.
  • Rate limit: 60 req/min/IP (nginx).

FAQ

How many tokens can I have?
10 active tokens per account. Revoked tokens stay in the list (for audit history) but no longer count toward the total.
What is the compile quota per plan?
Quota is in cumulative compile time over a rolling window: Free 1 min/2 h (no MCP access), Perso 5 min/2 h, Pro/Etab unlimited. Check is enforced both in the web editor and via MCP.
What happens if I create a new token with the same label?
The label is just a display indicator, not unique. You can have multiple tokens with the same label (they are distinguished by their prefix shown in the UI).
Do I need an LLM provider API key?
No. You use your existing AI client (your Claude Desktop, Cursor, Gemini CLI account…). Sarmate only provides the MCP token to access your drive. The two auths are independent.
Does it work with OAuth? And why not with Claude.ai (web/mobile)?
Currently the Sarmate MCP server only supports Bearer token auth (static tokens generated in the UI). This works perfectly with Claude Desktop, Claude Code, Cursor, Cline, Continue, Gemini CLI, ChatGPT (Developer Mode) and Le Chat.

However, Claude.ai (web/iOS/Android) requires full OAuth 2.1 authentication with /authorize and /token endpoints. If you try to connect, you'll get the error {"error":"not_found","path":"/authorize"}. OAuth is on our roadmap (no date). In the meantime, Claude Desktop and Claude Code give you exactly the same MCP capabilities with the same Anthropic AI.
Are my files sent to the AI?
Yes — as soon as you ask the AI to read or compile a file, the content flows through the AI provider (Anthropic, OpenAI, Google…). These providers apply their own retention and usage policies, to check on their side. Sarmate does not add retention beyond the audit log (which only contains call metadata, not file content).
Can I self-host the MCP server?
No, the Sarmate MCP server is centralised (it accesses your drive hosted on Sarmate servers). If your files are local, there are many open-source MCP servers (filesystem, git, etc.) in the official directory.
How do I debug a connection error?
Test the token with a direct curl (see section below). If it returns 200, the problem is client-side (config not reloaded, missing bridge for Claude Desktop, wrong URL…). If it returns 401, the token is invalid or revoked — create a new one.

Raw curl examples (debug)

Useful to validate that the server and your token work, independently of the 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)

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":2,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"thesis/main.tex"}}}'

Ready to try it?

Create a token in 30 seconds and copy the snippet that fits your client.

Create an account Back to overview