Setting

Value

Why

MCP_JSON_RESPONSES

false

Cloudflare returns error 524 when the origin sends nothing for 125 seconds, and a JSON-mode tool call sends nothing until it finishes — a slow LaTeX compile can trip it. SSE mode starts responding immediately and then streams. Note this is the opposite of the default, which is chosen for a same-host reverse proxy.

Bot Fight Mode

off

The assistants call from cloud IPs with non-browser user agents, so bot protection 403s them — and the client only reports "not a valid MCP server".

Cloudflare Access

do not enable

It requires an interactive login, which server-to-server clients cannot perform. LeafMCP runs its own OAuth; the consent page is opened in your browser, so Access would work for that one step and fail for everything else — a confusing half-broken state.

SSL/TLS mode

Full

Flexible is insecure and a common source of subtle breakage.

Tool

Description

list_projects

List every project in the account.

use_project

Select the working project by id, exact name, or a unique substring.

project_overview

File tree, plus the section structure of the main document and any unpublished changes.

Tool

Description

list_files

List project files with sizes.

read_file

Read a file with line numbers; supports start_line / end_line.

read_files

Read several files in one call.

search_project

Search all text files by substring or regular expression.

file_outline

Sections, labels, citations, includes and environments of one .tex file.

edit_file

Preferred. Replace an exact snippet; ambiguous matches are refused, and expected_hash refuses the edit if the file moved on since it was read.

write_file

Write a whole file, creating it if needed.

delete_file

Delete a file (requires explicit confirm=true).

rename_file

Rename or move a file.

pending_changes

List local edits not yet sent to Overleaf.

Tool

Description

compile

Compile on Overleaf; returns distilled errors/warnings and the PDF link.

publish_changes

Push pending local edits to Overleaf.

pull_project

Re-download the project from Overleaf.

edit_history

Recent changes, each labelled with its operation id.

undo_operation

Reverse one specific operation, leaving everything after it in place.

undo_last_edit

Reverse the last N edits and republish.

begin_change_set

Open a change set: the edits that follow are published together, or not at all.

commit_change_set

Publish the open change set in one go. A failure leaves it open to retry.

abandon_change_set

Discard the open change set and return the mirror to the state it opened from.

Tool

Description

list_comments

List comment threads with file and line.

add_comment

Add a comment, optionally anchored to a line.

reply_to_comment

Reply within a thread.

resolve_comment

Mark a thread resolved.

Variable

Default

Purpose

OVERLEAF_SESSION

—

Required. The overleaf_session2 cookie value.

PUBLIC_URL

http://localhost:8080

Exact public HTTPS origin. OAuth metadata is built from it.

MCP_AUTH_MODE

bearer

oauth, bearer, or none. Use oauth for the web clients.

MCP_OAUTH_PASSWORD

—

Required for oauth. The passphrase you type on the consent screen.

MCP_BEARER_TOKENS

—

Required for bearer. Comma-separated static tokens.

OVERLEAF_BASE_URL

https://www.overleaf.com

Point at a self-hosted instance.

OVERLEAF_EMAIL / OVERLEAF_PASSWORD

—

Self-hosted only: silent re-login when the cookie expires.

OLMCP_AUTO_PUSH

true

Publish each accepted edit immediately.

OLMCP_READ_ONLY

false

Refuse every mutating tool.

OLMCP_FRESH_READS

true

Re-fetch a file from Overleaf before reading or editing it.

OLMCP_DATA_DIR

./data

Where project mirrors and OAuth state live.

TRUST_PROXY

1

Number of reverse proxies in front. Set to 0 if directly exposed.

LOG_LEVEL

info

debug, info, warn, error. Logs go to stderr.

Severity

Issue

Fix

Critical

.git was reachable through the file tools. That is a command-execution primitive rather than mere repository corruption: git runs programs named by core.fsmonitor, core.hooksPath and filter.*.clean, and git add -A triggers them — confirmed against git 2.47, where all three vectors executed a payload. A prompt injection reaching one write call would have become code execution on the host.

Git's directory now lives outside the work tree (verified: the work tree contains no .git at all), the path layer rejects every .git* name, archives with such entries are skipped, and the git child runs with a minimal environment, no global config, and hooks and fsmonitor disabled.

Critical

Under MCP_AUTH_MODE=bearer (the default) the OAuth routes were still mounted, and that mode does not require MCP_OAUTH_PASSWORD — so an empty passphrase matched an empty passphrase, letting anyone self-register a client, approve it, and mint a token with full account access.

An empty passphrase never authorizes. OAuth routes are mounted only in oauth mode, and tokens issued earlier stop working outside it.

High

pull_project wiped the mirror before writing, so a failure part-way through left a partial tree; the next push read the missing files as deletions and removed them from Overleaf. The rollback added in the first fix was itself wrong — it deleted work-tree entries that had not been backed up yet, destroying the files it existed to protect.

Extract to a temporary directory and swap atomically. The rollback removes only what was installed and restores from the backup's actual contents. A push also refuses to delete every file at once.

High

compile auto-publishes pending edits but was the one write path with no read-only check, so a read-only connection could upload and delete files through it.

Read-only check added.

High

Publishing continued into the deletion phase after an upload failed. A rename is an upload plus a delete, so this left the project with neither the new file nor the old one — silent data loss from an operation the user read as a rename.

Any upload failure cancels the deletion phase; the change stays pending and the outcome reports that deletions were held back.

High

The consent screen was unthrottled, so the approval passphrase could be brute-forced.

Rate limited.

Medium

changes() returned an empty list on a git error (fail-open), silently skipping pushes and disabling the guard that protects unpublished edits.

Now throws (fail-closed).

Medium

undo_last_edit would reverse a reload from Overleaf, pushing a stale copy over browser edits and reporting success.

Only edit commits are undoable; reloads and refreshes are refused explicitly.

Medium

Refresh tokens could be replayed concurrently (both requests minted new tokens), and family revocation never actually matched — so a replayed token was merely refused while the stolen successor kept full access, contradicting what the README claimed.

Tokens carry a grant id; the claim is atomic; a replayed token revokes every token in its grant, access tokens included, so revocation is immediate. The regression test asserts the successor dies, not just that the old token is refused.

Medium

trust proxy: true trusted every proxy, so X-Forwarded-For could be spoofed to evade rate limiting.

Configurable hop count (default 1); true is unreachable.

Medium

A failed write permanently poisoned the OAuth store's write chain, breaking all later writes.

The chain stays settled; a single failure no longer propagates.

Medium

search_project compiled a model-supplied regex and ran it per line on the event loop, so catastrophic backtracking hung the whole server.

Nested-quantifier patterns rejected, plus a per-line cap and a time budget.

Medium

edit_file passed replacement text through String.replace, which expands $$, $& and $1. Writing $$E = mc^2$$ produced $E = mc^2$ — display math silently destroyed by the one tool whose job is editing LaTeX. The two replacement branches also disagreed.

A function replacer makes the text literal in both branches.

Medium

The ReDoS guard was a heuristic for nested quantifiers, and `(a

aa)+$` walked past it. Measured: 36 characters took ~6 seconds and 40 never finished, against a 4,000-character line cap — so one line of one file could wedge every request.

Medium

Dynamic client registration is unauthenticated by design, and nothing bounded it: client_name had no length limit, there was no cap on the number of clients, and the endpoint accepted the global 4 MB body. Each stored client is rewritten in full on every token operation, so this was an anonymous way to make the server do unbounded work.

Per-field length limits, a cap on registered clients, and a 16 KB body limit for the OAuth routes (the MCP route keeps 4 MB because a write_file call carries a file).

Medium

Project import had no limits. pull holds the whole archive in memory, so a project with a hundred thousand entries, one enormous entry, or a deeply nested path was enough to exhaust the process.

Entry count, per-entry and total extracted size, and path depth are all bounded; the declared size is checked before decompressing and the real size after, since a crafted archive can understate it.

Medium

The consent screen could be framed and cached. It is the one page where a click decides whether a stranger gets write access to someone's papers.

CSP with frame-ancestors 'none' and form-action 'self', plus X-Frame-Options: DENY, Cache-Control: no-store, a referrer policy and nosniff. There is no script on the page at all.

Low

The Docker build used npm install while CI used npm ci, so an image could contain dependency versions no lockfile ever pinned.

Both stages use npm ci.

High

Sync state was a single project-wide commit ref, so refreshing one file from Overleaf advanced the baseline past every file — another file's unpublished edit then looked already published and was never uploaded. Reproduced: an unpublished a.tex disappeared from pending_changes when b.tex was refreshed.

Sync state is now a per-file manifest of content hashes. Updating one entry cannot speak for another file, and the regression test asserts the pending file survives.

High

Change detection asked git, which fails open: git add's exit code was ignored, so a failed staging (a full disk, an unreadable file) could leave the index untouched and git diff --cached then reported no changes — the server would announce "already synced" about edits it had never sent, and the same empty list disabled the guard protecting unpublished work.

Detection hashes the files directly. Git is no longer in the trust path for deciding what to publish.

High

Read-only tools were outside the project lock, yet reading initialises the mirror, pulls it and refreshes files — all mutations. A read could race an edit and advance sync state on its behalf.

Every tool that can name a project now takes that project's lock. compile scopes its own critical section so a minute-long remote build does not block other clients.

Medium

Revocation deleted token rows but recorded no status, so a refresh already in flight when the grant was revoked could still write fresh, valid successors. Deleting records is a snapshot, not a state.

Grants have a durable revoked marker; minting consults it inside the same synchronous block as the insert, so a late write is refused rather than resurrecting the grant.

Medium

Upgrading from the old in-tree .git layout had no migration: the mirror looked uninitialised, so the next pull replaced the work tree — discarding unpublished edits — and the old configuration, which had lived inside the assistant-writable tree, would have been trusted.

Migration moves the git directory out, replaces the old config rather than reading it, clears hooks, and rebuilds the manifest from the old watermark so unpublished files stay unpublished. A work tree with files but no sync record now refuses to be pulled over.

Medium

The rate limiter kept one bucket per client address with no ceiling, and cleaned up by scanning the whole table once it grew past 1,000 keys — so the defence became the attack. The obvious fix, evicting the oldest bucket, is worse: an attacker rotating addresses evicts the record of their own abuse and starts over.

The table is capped and expired entries are dropped from the front (O(1) amortised, since keys are inserted in expiry order). Once full, unknown addresses share one overflow budget rather than displacing existing ones.

Medium

A full client table blocked every new registration until an operator edited a JSON file by hand; registrations accumulated with no reclamation.

Registrations that hold no live token and have no authorization in progress are reclaimed to make room. A client mid-consent is never reclaimed, and a reclaimable one simply registers again.

Medium

The isolated search process read files itself, so it inherited none of the read tool's limits — one large asset could be pulled into memory per search, and searches could be multiplied into as many processes as there were requests.

Per-file and total byte budgets inside the worker, plus a ceiling on concurrently running searches.

Medium

delete_file on a directory removed everything inside it, published the deletions, and reported success — the caller had named a folder, not its contents.

A directory is refused on the first attempt and its contents are listed; recursive=true is required to proceed, and the result states how many files went.

Medium

Only a target's final path segment was checked for being a symlink, so a linked directory let a write land outside the project while the path still looked contained.

The resolved ancestor chain is checked against the resolved project root, for writes, moves and deletions. The remaining check-to-open window is documented rather than claimed closed.

Medium

Credential redaction registered only the literal secret, so a value that travelled percent-encoded appeared in logs in a form the pattern did not match.

Secrets are registered with their decoded variant as well, one level deep — repeated decoding of attacker-influenced text is its own problem.

Low

Extra callback patterns were matched as regular expressions against a URL, so an unescaped . in a hostname quietly widened what was accepted, and an unanchored pattern matched a URL that merely contained the callback as a parameter.

Exact URLs are the preferred configuration (MCP_OAUTH_REDIRECT_URLS); patterns are validated at startup and the server refuses to run unanchored or unescaped ones, with --check explaining why.

Low

Four OAuth settings (MCP_OAUTH_CLIENT_ID, _CLIENT_SECRET, _AUTHORIZE_URL, _TOKEN_URL) were parsed but never read, implying a pre-registration mode that does not exist.

Removed. This server is the authorization server, so those settings had no meaning to implement.

Low

Session re-authentication matched a bare login substring, so an unrelated error mentioning it could tear down a working session; and an old expired call cleared whichever session was current, discarding one another call had just rebuilt.

Matching is phrase-based against the client's actual wording, and only the session that failed is discarded.

Low

Dot files were hidden from listings but readable by name, and an extensionless one like .latexmkrc was classified as binary and refused.

Only git's own names are hidden; a leading dot is no longer treated as an extension. Listing and reading now agree.

Low

OAuthStore initialised from a shared constant with a shallow copy, so every instance pointed at the same nested clients, tokens and revoked objects. One store mutating another's state went unnoticed because production runs a single instance.

A factory function returns genuinely independent state. Found by a test that seeded two stores.

Low

use_project had no read-only check and writes global state, so a read-only connection could retarget another client's edits.

Read-only check added.

Low

MCP_AUTH_MODE=none granted anonymous write access.

Read-only by default; requires OLMCP_ALLOW_ANONYMOUS_WRITE=true to opt in.

Low

Static tokens were compared in non-constant time; redaction missed custom cookie names; successful tool output bypassed redaction.

Constant-time comparison, runtime-registered secrets, output redacted too.

Symptom

Cause and fix

Client says "not a valid MCP server"

Clients POST initialize straight to the registered URL and never use legacy SSE. Make sure you entered https://domain/mcp (not /sse) and that /healthz is publicly reachable.

Tool calls fail after roughly two minutes (Cloudflare error 524)

The origin sent nothing for 125 seconds. Set MCP_JSON_RESPONSES=false so responses stream; a JSON-mode call stays silent until the tool finishes.

"Not a valid MCP server" only when behind Cloudflare

Bot Fight Mode is rejecting the assistants, which call from cloud IPs with non-browser user agents. Turn it off for the zone, or add a WAF skip rule for the hostname.

Connection times out

Requests come from the vendors' clouds. Check for an IPv4 A record, a valid certificate, and no firewall rule limited to your own IP. Anthropic's egress range is 160.79.104.0/21.

Consent page will not open, or authorization fails

PUBLIC_URL must match the address clients use exactly. The resource in the discovery metadata must equal the MCP URL precisely; clients validate it strictly.

Tools fail with a session error

overleaf_session2 changes when you log out or the session expires. Copy it again. Self-hosted instances can set OVERLEAF_EMAIL / OVERLEAF_PASSWORD for automatic re-login.

Not sure which part is broken

Run node dist/index.js --verify. It reports each Overleaf call separately and writes nothing, so the failing line names the problem.

Changes do not appear in Overleaf

Check pending_changes. If OLMCP_AUTO_PUSH=false, you need an explicit publish_changes. Failed files are listed with reasons in the tool result.

Compile fails but the local file looks fine

compile publishes first and reports an error rather than compiling stale content. Check pending_changes.