MCP Server

Connect AI clients to a project through its MCP server on a Kubernetes deployment.

Each project’s MCP server runs in the web service (the mcp-server module) of every Ayakaleaf Pro pod. It comes with the Git integration and has no setting of its own. How to connect Claude Code, Codex and other clients is described in MCP Server.

Service	web, in every Ayakaleaf Pro pod
Switched on by	GIT_BRIDGE_ENABLED: "true" and the git-bridge StatefulSet, see Git integration
Outside → Overleaf	AI clients POST ${OVERLEAF_SITE_URL}/project/<id>/mcp with a Git authentication token; PDF download links under ${OVERLEAF_SITE_URL}/project/<id>/mcp/download/
Pod → outside	none
State	none between requests; compile output stays on the pod that compiled
Periodic jobs	none

Configuration

Set up the Git integration. The MCP server is then at ${OVERLEAF_SITE_URL}/project/<project id>/mcp, and the address must be reachable from where the AI client runs.

Several replicas

A compile through MCP runs on the replica that received the request, and its log and PDF exist only there. AI clients send no cookie, so the load balancer may send the next request, get_compile_log or the PDF download link, to another replica, which answers “failed to fetch output file from CLSI” or 404. In our test with three replicas and no extra rule, 5 of 6 log requests and 3 of 4 downloads failed this way.

Route every MCP request of a project to one replica, as for /git/. With HAProxy from Horizontal scaling:

      use-server overleaf-0 if { path_reg ^/project/[0-9a-f]{24}/mcp(/|$) }

MCP compiles then all run on overleaf-0’s node. With another ingress controller, route the path /project/<id>/mcp and everything below it to one replica’s own name (overleaf-0.overleaf-hl).

With this rule, the same test (a compile, 6 log requests and 4 PDF downloads, all without a cookie) succeeded every time.

Tested on Kubernetes

On Kubernetes 1.37 with three replicas behind HAProxy, our end-to-end tests for the MCP server pass (37 cases): listing the tools, tokens refused when wrong, deleted or without access, compiling and reading the log, word count, project settings and history, PDF download links, editing files with the changes shown live in the open editor and pulled into a Git clone, comments, access by role, the compile and settings rate limits, and suspended accounts. These requests came from a browser session, so the load balancer kept them on one replica; for clients without a cookie, see Several replicas.