Compile LaTeX from Claude Code or Cursor with the Octree MCP Server

Claude Code and Cursor write LaTeX well, but on their own they cannot tell whether it compiles. You either install a full TeX distribution next to the agent or copy the source into an editor and read the log yourself. The Octree MCP server removes that step: it gives your agent a compile_latex tool that turns LaTeX into a PDF and a check_latex tool that reports errors by file and line, both running on the same compiler as the Octree editor.

This guide covers what the LaTeX MCP server does, how to add it to Claude Code, Cursor, Windsurf and VS Code, the loop an agent should follow, the REST API for scripts, and the limits.

What the Octree LaTeX MCP Server Does

The server lives at https://app.useoctree.com/api/mcp. It speaks the Streamable HTTP transport and is stateless, so there is no session to set up or keep alive. It runs TeX Live with latexmk, so there is nothing to install and every package is already there. You authenticate with an Octree API key in an Authorization: Bearer oct_live_… header. It exposes three tools:

• compile_latex takes latex (a single document) or files plus main, and returns a short summary (pages and compile time, or the errors) with the PDF as a resource.
• check_latex takes the same input and returns errors only, each with file, line and kind. It is the fast loop for an agent fixing a document, and it counts toward the daily quota.
• get_quota takes no input and returns your plan, daily limit, compiles used today and resets_at.

Every error has a kind: missing_package, undefined_control_sequence, missing_dollar, missing_brace or latex_error. The agent can branch on the error type and jump to the right line without ever reading a raw LaTeX log.

Quick Start: Claude Code

Create a key under Settings → API keys in the Octree app. It starts with oct_live_ and is shown once, so copy it somewhere safe. Then add Octree as a remote MCP server:

1claude mcp add --transport http octree https://app.useoctree.com/api/mcp \
2  --header "Authorization: Bearer oct_live_…"
Copy

Now ask Claude Code something like “Write main.tex for a two-page lab report and compile it with Octree.” Claude writes the file, calls the tools and hands you the PDF.

Quick Start: Cursor, Windsurf and VS Code

Clients that read an mcpServers config take a remote server with a URL and headers. In Cursor this goes in ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

1{
2  "mcpServers": {
3    "octree": {
4      "url": "https://app.useoctree.com/api/mcp",
5      "headers": {
6        "Authorization": "Bearer oct_live_…"
7      }
8    }
9  }
10}
Copy

Windsurf and other MCP clients, including VS Code, use the same URL and Authorization header in their own MCP config file; some name the field serverUrl instead of url, so check your client’s docs for the exact key names.

Keep the key out of shared repositories: put it in your user-level config, or use your client’s environment-variable substitution if it has one.

An Example Agent Loop: Write, Check, Compile

The tools are designed for a short, cheap fix loop. An agent should:

1. Write the .tex files first, with \documentclass in the main file.
2. Call check_latex and fix what it reports, using the file, line and kind of each error.
3. Fix all reported errors before checking again, because every check counts toward the daily quota. Repeat until the check comes back clean.
4. Call compile_latex once to get the PDF.

Each check returns only the errors, not a PDF, so the loop stays small. A minimal main.tex an agent might start from:

1\documentclass{article}
2\usepackage{amsmath}
3\title{Lab Report}
4\begin{document}
5\maketitle
6\section{Results}
7The measured period follows
8\begin{equation}
9  T = 2\pi\sqrt{\frac{L}{g}}.
10\end{equation}
11\end{document}
Copy

If you write instructions for your agent (a CLAUDE.md, Cursor rules or a system prompt), this one line is enough:

1To build LaTeX, use the octree MCP tools: run check_latex until there are no errors, then compile_latex once to get the PDF.
Copy

Compile LaTeX over the REST API

Scripts, CI jobs, backends and agent frameworks that call HTTP directly can use the compile LaTeX API with the same key. Send POST https://app.useoctree.com/api/v1/compile with a JSON body containing either latex or a files array (plus an optional main):

1export OCTREE_API_KEY=oct_live_…
2
3curl https://app.useoctree.com/api/v1/compile \
4  -H "Authorization: Bearer $OCTREE_API_KEY" \
5  -H "Content-Type: application/json" \
6  -d '{"latex":"\\documentclass{article}\\begin{document}Hello\\end{document}"}'
Copy

A document that compiles returns ok: true with the PDF in pdf_base64, plus pages and duration_ms. A document with LaTeX errors is still a successful request: HTTP 200 with ok: false and an errors list of { file, line, message, kind }. Set "response": "pdf" (or send Accept: application/pdf) to get the raw PDF instead. GET /api/v1/me returns your plan and today’s usage, and the OpenAPI description is at app.useoctree.com/api/v1/openapi.json.

Limits and API Keys

• Free: 30 compiles per day. Pro: 1,000 compiles per day. The count resets at midnight UTC.
• REST and MCP share the same count, and check_latex counts like a compile. When you run out, the API answers HTTP 429 with quota_exceeded.
• Requests can carry up to 2 MB of source and 50 files.
• Keys are created under Settings → API keys, start with oct_live_, are shown once, and you can have up to 5 per account. Revoke any of them at any time in Settings.

What Octree Does Not Store

On the API and MCP path, the LaTeX source and the PDF are not stored after the response is sent. Projects you create in the Octree editor are saved to your account as usual; that is separate from the API. Shell escape is disabled, so packages that need it, such as minted, do not run.

FAQ

Is the Octree LaTeX MCP server free?

Yes. Every Octree account can create API keys, and the free plan includes 30 compiles per day through the MCP server and the REST API. Octree Pro raises the limit to 1,000 compiles per day.

Which MCP clients does it work with?

Any client that supports remote MCP servers over Streamable HTTP with a custom Authorization header, including Claude Code, Cursor, Windsurf and VS Code. Claude Code uses claude mcp add --transport http; the others take a URL and headers in their MCP config file.

Can I compile multi-file LaTeX projects?

Yes. Send a files array of { path, content } objects plus the name of the main file, and \input, \include and .bib files resolve as they would on disk. In v1 every file is text, and a request can carry up to 50 files and 2 MB of source.

Which LaTeX engine does it use?

Documents compile with pdfLaTeX by default. When a document needs XeLaTeX or LuaLaTeX, for example because it loads fontspec, the compiler switches automatically, so there is no engine option to set.

How are API keys kept secure?

Keys start with oct_live_ and are shown once, when you create them. Octree keeps only a hash of each key, so a key cannot be read back, only revoked. You can have up to 5 keys per account and revoke any of them in Settings.