overleaf-setup skill
Install, authenticate, and troubleshoot the Overleaf MCP server to manage projects and sessions.
- GitHub stars
- 14
- Files
- 1
- Last commit
- Sep 20, 2026
- License
- AGPL-3.0
- Allowed tools
- —
What does the overleaf-setup skill do?
overleaf-setup is an agent skill. Install, authenticate, and troubleshoot the Overleaf MCP server to manage projects and sessions.
Summary generated from the skill's SKILL.md.
About the overleaf-setup skill
Setting up and troubleshooting the connection between an AI agent and Overleaf is what this skill facilitates. It helps developers install the overleaf-mcp-rt server, authenticate sessions using browser-based login or manual cookie entry, and resolve common connection errors. An agent should load this skill when Overleaf tools are missing, when a session cookie has expired, or when a user needs to connect a new hosted or self-hosted Overleaf instance.
Users can manage multiple hosts and use the diagnose command to identify failures across the configuration, REST API, or OT handshake layers. The skill handles specific error codes like OVERLEAF_AUTH_FAILED or PROXY_AUTH_FAILED by providing the necessary corrective actions. It also manages complex scenarios involving authentication proxies via OVERLEAF_EXTRA_HEADERS and handles document format issues like HISTORY_OT_WRITES_DISABLED by suggesting environment variable changes. This ensures the agent can maintain a stable connection to LaTeX projects without requiring a server restart after a new login.
What an agent can do with it
- 1Authenticate a new Overleaf sessionHelp the user log in to a hosted Overleaf instance using a browser to capture their session automatically.
- 2Troubleshoot connection failuresIdentify exactly where the connection is failing between the configuration and the Overleaf load balancer.
- 3Configure access through a proxySet up additional headers to bypass authentication blocks from reverse proxies like Cloudflare Access.
- 4Resolve document format errorsEnable editing for projects using newer document formats that have history writes disabled by default.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the overleaf-setup skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the overleaf-setup skill in Plugin
/plugin marketplace add DanielHou315/overleaf-mcp-rt /plugin install overleaf-mcp-rt@overleaf-mcp-rt
Install the overleaf-setup skill in Claude Code
~/.claude/skills/overleaf-setup/SKILL.md
$ npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup ~/.claude/skills/overleaf-setupInstall the overleaf-setup skill in Claude Code (project)
.claude/skills/overleaf-setup/SKILL.md
$ npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup .claude/skills/overleaf-setupInstall the overleaf-setup skill in Codex
~/.agents/skills/overleaf-setup/SKILL.md
$ npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup ~/.agents/skills/overleaf-setupInstall the overleaf-setup skill in Gemini CLI
~/.gemini/skills/overleaf-setup/SKILL.md
$ npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup ~/.gemini/skills/overleaf-setupInstall the overleaf-setup skill in Claude.ai
npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup overleaf-setup && zip -r overleaf-setup.zip overleaf-setup # claude.ai → Customize → Skills → + → Create skill → Upload a skill → overleaf-setup.zip
SKILL.md
View on GitHubSetting up overleaf-mcp-rt
The server needs one thing per Overleaf instance ("host"): a logged-in session cookie. Only the user can log in — you prepare the command, they run it.
Log in (or refresh an expired session)
Ask the user to run this. It opens a browser window with a throwaway profile; they sign in as usual (CAPTCHA, SSO and 2FA all work) and the session is captured automatically:
npx -y overleaf-mcp-rt login --url https://overleaf.example.com --browser
npx -y overleaf-mcp-rt login --url https://www.overleaf.com --name overleaf.com --browser # hosted Overleaf
- No prompts are asked when
--urland--browserare both given, so it also runs from a non-interactive shell (for instance a harness's "run this command for me" prefix). - The first host becomes the default; add
--defaultto change it. - Headless machine?
login --url … --cookie '<value>'with theoverleaf_session2(overleaf.com),overleaf.sidorsharelatex.sidcookie copied from browser devtools. Self-hosted instances without CAPTCHA also accept--email. - Never ask the user to paste a password or cookie into the chat, and never read
~/.config/overleaf-mcp-rt/credentials.jsonyourself.
A running MCP server picks up a new or refreshed login on the next tool call — no restart needed.
Check it works
npx -y overleaf-mcp-rt hosts # configured hosts (names and URLs only)
npx -y overleaf-mcp-rt diagnose [--host NAME] # config → REST → projects → load balancer → OT handshake
diagnose names the failing layer. Then call overleaf_list_hosts and overleaf_list_projects.
Register the server with an MCP client
If this skill came from the overleaf-mcp-rt plugin, the server is already registered. Otherwise add a stdio server to the client's MCP config:
{ "mcpServers": { "overleaf": { "command": "npx", "args": ["-y", "overleaf-mcp-rt"] } } }
Most harnesses also have a one-liner, e.g. claude mcp add overleaf -- npx -y overleaf-mcp-rt or codex mcp add overleaf -- npx -y overleaf-mcp-rt. Behind an auth proxy (Cloudflare Access, basic auth), set OVERLEAF_EXTRA_HEADERS to a JSON object of headers, or pass --header KEY=VALUE to login.
Reading errors
| Code | Meaning | Fix |
|---|---|---|
OVERLEAF_AUTH_FAILED |
Session expired or invalid | User re-runs login … --browser |
INVALID_CONFIG |
No such host / nothing configured | hosts, then login |
PROXY_AUTH_FAILED |
A reverse proxy blocked the request | OVERLEAF_EXTRA_HEADERS |
PROJECT_ACCESS_DENIED |
This account isn't a collaborator | User shares the project with it |
COMMENTS_UNSUPPORTED |
Stock Community Edition has no review panel | Not fixable on that host |
| joinDoc refused: "history-ot" | Version of this tool older than 2.2.0, on a project using Overleaf's newer document format | Update overleaf-mcp-rt |
HISTORY_OT_WRITES_DISABLED |
Project on Overleaf's newer document format: readable, but editing is opt-in | Tell the user; they enable it by starting the server with OVERLEAF_HISTORY_OT_WRITES=1 (scratch file first). Until then give them the change as text |
HISTORY_OT_MISMATCH |
Overleaf stored something other than predicted after a write | Stop editing that project, re-read, tell the user to report it |
Files in this skill
1overleaf-setup skill questions
How do I install the overleaf-setup skill in Claude Code?
Run npx degit DanielHou315/overleaf-mcp-rt/skills/overleaf-setup ~/.claude/skills/overleaf-setup. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the overleaf-setup skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I log in to a new Overleaf instance?
You can run the login command with the --url and --browser flags to open a browser window for automatic session capture.
What should I do if I get an OVERLEAF_AUTH_FAILED error?
This error means the session has expired or is invalid; the user should re-run the login command using the browser flag.
How can I check if the Overleaf MCP server is working correctly?
Use the diagnose command to check the configuration, REST connection, projects, load balancer, and OT handshake.
How do I handle authentication proxies like Cloudflare Access?
Set the OVERLEAF_EXTRA_HEADERS environment variable to a JSON object of headers or use the --header flag during login.