AI Integration (MCP)

Lerd ships a Model Context Protocol server, letting AI assistants manage your dev environment directly: run migrations, start services, toggle queue workers, and inspect logs without leaving the chat.

Supported assistants: Claude Code, Cursor, JetBrains Junie, Codex CLI, Gemini CLI, GitHub Copilot (VS Code), Google Antigravity, Windsurf, and any other MCP-compatible tool.

---

Setting up MCP

There are two ways to connect lerd to your AI assistant: globally (recommended) or per-project.

Global registration (recommended)

Run once after installing lerd:

lerd mcp:enable-global

This registers the lerd MCP server at user scope, available in every session regardless of which directory you open, and writes user-scope context files so the assistant knows what lerd tools are available and how to use them.

MCP server registration:

Client	Registration
Claude Code	claude mcp add --scope user (CLI)
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
JetBrains Junie	~/.junie/mcp/mcp.json
Gemini CLI	~/.gemini/settings.json
Codex CLI	~/.codex/config.toml
GitHub Copilot (VS Code)	~/.config/Code/User/mcp.json
Google Antigravity	~/.gemini/config/mcp_config.json

Context / instructions files:

File	Purpose
~/.claude/skills/lerd/SKILL.md	Claude Code user-scope skill
~/.cursor/rules/lerd.mdc	Cursor user-scope rules
~/.junie/guidelines.md	JetBrains Junie user-scope guidelines (merged, not overwritten)
~/.gemini/GEMINI.md	Gemini CLI user-scope context (merged)
~/.codex/AGENTS.md	Codex CLI user-scope context (merged)

All clients share a single canonical tool reference, so the guidance never drifts between assistants. When running globally, the server uses the directory the assistant is opened in as the site context: no further configuration is needed.

Claude Code is registered via its own claude mcp add CLI rather than by editing ~/.claude.json directly, since that file holds all of Claude's user state.

GitHub Copilot uses VS Code's servers key (each entry typed stdio), which differs from the mcpServers key the other clients use. Its instructions file (.github/copilot-instructions.md) is project-scoped only.

Google Antigravity registers at ~/.gemini/config/mcp_config.json (its project-scoped MCP config is not honoured, so it is global only). It auto-loads GEMINI.md and AGENTS.md, which the Gemini and Codex entries already write, so no separate Antigravity context file is needed.

During lerd install: If Claude Code is detected, you'll be prompted to run this automatically.

During lerd update: When MCP is globally registered, the context files that already exist are rewritten from the newly installed binary so they stay in sync with any added or renamed tools. Update never creates files for a client you haven't set up, to pick up a newly supported assistant, re-run lerd mcp:enable-global.

Project-scoped registration

To commit the lerd MCP config into a project so every teammate picks it up from git:

cd ~/Lerd/my-app
lerd mcp:inject

This writes MCP config and context files for every supported client into the project directory:

File	Client
.mcp.json	Claude Code MCP config
.claude/skills/lerd/SKILL.md	Claude Code skill
.cursor/mcp.json	Cursor MCP config
.cursor/rules/lerd.mdc	Cursor rules
.junie/mcp/mcp.json	JetBrains Junie MCP config
.junie/guidelines.md	JetBrains Junie guidelines (merged)
.gemini/settings.json	Gemini CLI MCP config
GEMINI.md	Gemini CLI context (merged)
.vscode/mcp.json	GitHub Copilot (VS Code) MCP config
.github/copilot-instructions.md	GitHub Copilot instructions (merged)
AGENTS.md	Codex CLI context (merged)

The written entries carry no machine-specific data: the server resolves the site from the directory the assistant is opened in, exactly like a global registration. A committed .mcp.json therefore stays identical across every teammate's checkout, with no absolute path to drift or break on another machine. (An older lerd wrote a LERD_SITE_PATH absolute path into these files; it is still honoured if you set it by hand, but no longer written.)

Codex and Windsurf have no project-scoped MCP config (Codex reads only ~/.codex/config.toml, Windsurf only ~/.codeium/windsurf/mcp_config.json), so mcp:inject writes their context but not a per-project server entry. Register them once with lerd mcp:enable-global. lerd used to write a Windsurf entry into .ai/mcp/mcp.json, but that path was never Windsurf's (it belongs to Laravel Boost), so lerd no longer touches it and strips any entry an older version left behind.

The command merges into existing configs; other MCP servers (e.g. laravel-boost, herd) and any existing instructions content are left untouched. Re-running it is safe.

To target a different directory:

lerd mcp:inject --path ~/Lerd/another-app

To reverse an injection, lerd mcp:eject (with an optional --path) strips every lerd-owned entry and skill file back out of the project, leaving other MCP servers and your own instructions content intact. The user-scope equivalent is lerd mcp:disable-global.

During lerd update: Projects that previously ran mcp:inject are detected automatically (by the presence of .claude/skills/lerd/SKILL.md, .cursor/rules/lerd.mdc, or the lerd marker in .junie/guidelines.md) and refreshed in place. Only files that already exist for a client are rewritten, so update never drops new client files into your repo; re-run mcp:inject to add a newly supported assistant. Directories whose content already matches the new binary stay untouched, so git status stays clean. Projects that never opted in are skipped.

To opt a project out of this automatic refresh entirely, set mcp_inject: false in its .lerd.yaml. lerd then never rewrites that project's MCP config or skill files on a self-update, which is the right choice when you keep those files under version control and want them changed only when you say so. An explicit lerd mcp:inject still writes when you run it, since that is you asking directly.

Path resolution

Most actions accept an optional path argument. When omitted, the server resolves it in this order:

1. Explicit path argument (highest priority)
2. LERD_SITE_PATH env var (honoured if set by hand; lerd no longer writes it)
3. Current working directory, the directory the assistant was opened in

Agent detection passthrough

PHP runs inside the container, so the AI agent environment variables your coding agent exports on the host (CLAUDECODE, AI_AGENT, CURSOR_AGENT, GEMINI_CLI, and the rest of the agent-detector set) would normally be lost at the container boundary. lerd forwards any that are present into the container for lerd php, lerd artisan, and tinker, so packages like laravel/pao still detect the agent and emit their compact JSON output.

Commands the exec MCP tool runs (artisan, composer, vendor_run for Pest/PHPUnit) go a step further: because reaching them through the MCP server proves an agent is driving the command, lerd injects a neutral AI_AGENT=lerd-mcp marker when no real agent variable is present. Pao therefore returns JSON for MCP-originated test runs even if the host environment carries nothing, while a real agent variable is still forwarded as-is when it exists. Manual terminal runs are never given the marker, so their output is unchanged.

---

Available MCP tools

The MCP surface is twelve grouped tools, each driven by an action argument. Always pass action; start by calling site with action: "list" to discover sites.

Tool	Actions
site	list (discover sites, call first), link, unlink, domain_add, domain_remove, group_assign, group_unassign, group_label, group_db, group_list, tls_enable, tls_disable, tls_renew, php, node, pause, unpause, restart, rebuild, runtime, nginx_read, nginx_write, nginx_reset, park, unpark
service	start, stop, restart, pin, unpin, update, rollback, migrate, remove, reinstall, add, expose, port, env, config_read, config_write, config_restore, config_reset, config_list_backups, preset_list, preset_search, preset_install, check_updates
db	list, set, move, create, export, import, snapshot, snapshots, restore, snapshot_delete
env	setup, check, override
runtime	versions, node_install, node_uninstall, php_list, ext_list, ext_add, ext_remove, ports_list, ports_add, ports_remove, ini_read, ini_write, ini_reset
worker	list (call first), start, stop, add, remove, health, heal, mode_get, mode_set, queue_start, queue_stop, horizon_start, horizon_stop, reverb_start, reverb_stop, schedule_start, schedule_stop, stripe_start, stripe_stop, stripe_config
exec	artisan, console, composer, vendor_bins, vendor_run, commands_list, commands_run, command_add, command_remove
framework	list, add, remove, prune, search, update, project_new, setup
diag	status, doctor, doctor_fix, site_doctor, which, check, dns_diagnose, bug_report, analyze_queries, route_timing, optimize_route, dumps_recent, dumps_status, dumps_clear, dumps_toggle, profiler_toggle, profiler_status, profiler_clear, profiler_report, xdebug_on, xdebug_off, xdebug_status
logs	sources, fetch
worktree	list, add, remove, db_isolate, db_share
workspace	list, create, rename, delete, assign, move

The injected context files document each action's arguments and the key conventions in full.

Workspaces are not site groups

The two are easy to confuse and an assistant reaching for the wrong one does the wrong thing.

A workspace (the workspace tool) is a display-only bucket that organises the site list in the dashboard sidebar and the TUI. It never touches nginx, domains, certificates or .env. Use it when someone wants their sites sorted by client or by project.

A site group (the site tool's group_* actions) nests a real site under another site's subdomain, at <label>.<main>.test, and regenerates vhosts and certificates to serve it. Use it when a site should actually be reachable at that address.

Service presets carry their own discovery metadata

preset_list returns each preset's category, icon and admin_for. admin_for names the services a preset's admin UI administers, and it is not depends_on: phpMyAdmin depends on mysql (satisfied by MariaDB via env_role) but administers both, and RedisInsight depends on redis (satisfied by Valkey) while administering both. To answer "which dashboard administers this database", read admin_for.

service start/stop/restart use the same serviceops path as the CLI, Web UI, and TUI: depends_on resolution (including family / env_role drop-ins), reverse-dependent start, soft stop cascade, and discover_family / pinned-dependency-host consumer regen. Stop failures surface as errors rather than a silent OK. Do not assume MCP is a thinner StartUnit wrapper.

Reading logs

The logs tool lets an assistant debug a site's logs without opening files by hand. Call logs with action: "sources" to list every queryable source for a site (app:<file> framework logs, fpm, worker:<name>) plus shared infrastructure (nginx, dns, watcher, ui, services, php<ver>), then action: "fetch" with a source and any of grep (regex or literal substring), since/until (relative like 15m/2h30m, or a timestamp), level (app logs only), and lines. Each fetch returns an opaque cursor; pass it back as since on the next call to receive only the new lines, which is how streaming is modelled over MCP's request/response transport. See the logs feature page for the full source list, filter semantics, and platform notes.

Grouped surface: earlier lerd versions exposed ~80 individual MCP tools (sites, artisan, db_set, …). These were consolidated into the grouped tools above to cut the per-session token cost and sharpen the model's tool selection. Old flat tool names no longer exist; call the group with the matching action instead (e.g. artisan → exec with action: "artisan", db_set → db with action: "set").

---

Example interactions

The path argument is omitted from most calls; the server resolves it from the directory the assistant was opened in.

You: create a new Laravel project and get it running
AI:  → framework(action: "project_new", path: "/home/me/Code/myapp", framework: "laravel")
       # scaffolds + runs composer install, returns with vendor/ populated
     → site(action: "link", path: "/home/me/Code/myapp")
     → env(action: "setup", path: "/home/me/Code/myapp")
       # detects MySQL + Redis (or keeps sqlite), starts services, creates DB, generates APP_KEY
     → framework(action: "setup", path: "/home/me/Code/myapp")
       # runs storage:link + migrate
     ✓  myapp -> myapp.test ready

You: run migrations
AI:  → exec(action: "artisan", args: ["migrate"])
     ✓  Ran 3 migrations in 42ms

You: install sanctum and run its migrations
AI:  → exec(action: "composer", args: ["require", "laravel/sanctum"])
     → exec(action: "artisan", args: ["vendor:publish", "--provider=Laravel\\Sanctum\\SanctumServiceProvider"])
     → exec(action: "artisan", args: ["migrate"])

You: add a MongoDB service
AI:  → service(action: "add", name: "mongodb", image: "docker.io/library/mongo:7", ports: ["27017:27017"], data_dir: "/data/db")
     → service(action: "start", name: "mongodb")
     ✓  mongodb started

You: add phpMyAdmin, it needs MySQL to be running
AI:  → service(action: "preset_install", name: "phpmyadmin")
     → service(action: "start", name: "phpmyadmin")
       # starts mysql first (dependency), then phpmyadmin
     ✓  mysql started
     ✓  phpmyadmin started

You: what PHP and Node versions are installed?
AI:  → runtime(action: "versions")
     { "php": { "installed": ["8.4", "8.5"], "default_version": "8.5" },
       "node": { "installed": ["v20.11.0", "v18.20.4"], "default_version": "20" } }

You: set up the project I just cloned
AI:  → site(action: "link")
     → exec(action: "composer", args: ["install"])
       # runs BEFORE env setup so APP_KEY generation has vendor/
     → env(action: "setup")
       # detects MySQL + Redis, starts them, creates database, generates APP_KEY
     → framework(action: "setup")
       # framework migrations + storage:link (or doctrine:migrations:migrate for Symfony)
     ✓  whitewaters -> whitewaters.test ready

You: enable xdebug so I can step through a failing job
AI:  → diag(action: "xdebug_status")
     → diag(action: "xdebug_on", version: "8.5")
     ✓  Xdebug enabled for PHP 8.5 (mode=debug, port 9003)

You: start the queue worker
AI:  → worker(action: "list", site: "myapp")
     → worker(action: "queue_start", site: "myapp")
     ✓  queue worker started for myapp

You: the app is throwing 500s, check the logs
AI:  → logs(action: "sources", site: "myapp")
     → logs(action: "fetch", source: "app:laravel.log", level: "error", since: "15m")
     PHP Fatal error: Class "App\Jobs\ProcessOrder" not found ...

You: this site feels slow, optimize it
AI:  → diag(action: "route_timing", site: "myapp")
       # GET /reports/:id runs at 1080ms p95, 27x the site's 40ms median
     → diag(action: "dumps_toggle", enable: true)
       # then hit the slow route a couple of times so queries are captured
     → diag(action: "optimize_route", site: "myapp")
       { "routes": [ { "route": "GET /reports/:id", "p95_millis": 1080,
         "evidence": [ { "n_plus_one": [ { "count": 38,
           "fingerprint": "select * from line_items where report_id = ?",
           "caller": { "file": "app/Http/Controllers/ReportController.php", "line": 44 } } ] } ] } ] }
     # the N+1 and its exact caller, from real traffic, not from reading code