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, OpenCode, 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
OpenCode	~/.config/opencode/opencode.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)
~/.config/opencode/AGENTS.md	OpenCode 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.

OpenCode uses neither of the other two shapes: its entry sits under an mcp key, is typed local rather than stdio, and takes the whole invocation as a single command array. It reads AGENTS.md from the project root, which the Codex entry already writes, so only its own ~/.config/opencode/AGENTS.md is written separately. OpenCode also reads opencode.jsonc, and its own documentation asks for one format per directory, so where a .jsonc already exists lerd merges into that file rather than leaving a .json beside it that may never be read. The rewrite emits plain JSON, so comments in that file are not preserved.

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, also read by OpenCode (merged)
opencode.json	OpenCode MCP config

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.

Running your framework's own MCP server

This is separate from lerd's MCP server. Some frameworks ship their own local MCP server, started as a console command — Laravel MCP does, and it is what Laravel Boost builds on. Such a server has to run where the application runs: started from the host it resolves lerd-mysql or lerd-redis against nothing, and you end up maintaining a second set of host-only .env values just to keep it alive.

lerd's php shim already takes care of that. The installer puts lerd's bin directory ahead of the system one on your PATH, and the php there execs into the project's container, so the ordinary registration works unchanged:

{
  "mcpServers": {
    "weather": {
      "command": "php",
      "args": ["artisan", "mcp:start", "weather"]
    }
  }
}

The server then runs on the same PHP build, the same extensions and the same container network as the site, and the hostnames in your .env resolve exactly as they do for a web request.

A client you launch from a desktop icon rather than a terminal may not inherit your login PATH, in which case it finds the system php instead of the shim. Name lerd explicitly there:

{
  "mcpServers": {
    "weather": {
      "command": "lerd",
      "args": ["artisan", "mcp:start", "weather"]
    }
  }
}

Either form leaves stdout to the server: anything lerd needs to say while starting a container or a service goes to stderr, so it never lands in the middle of the JSON-RPC stream.

---

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, entities, entity_action
db	list, set, move, create, export, import, snapshot, snapshots, restore, snapshot_delete, snapshot_keep, auto, auto_set, extension_list, extension_add
env	setup, check, override
runtime	versions, node_install, node_uninstall, node_manager, 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, wait, 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.

Creating a worktree from an assistant

worktree add blocks until the watcher's setup pipeline has finished and reports provisioned: true, because the pipeline starts the moment git writes the worktree entry, and an action that returned earlier would hand back a tree being written underneath the assistant. Two installers in one tree is how vendor/ ends up with packages extracted but no autoload.php, which then presents as a Composer autoload bug rather than a race.

wait is the same check on its own, for a worktree created with plain git or after add with wait=false. Both accept timeout_seconds (default 300) and report provisioned: false with a note rather than an error when setup is still running, since an unfinished install is a "not yet", not a failure.

An assistant should never infer readiness from the tree's contents. node_modules/ exists from the first extracted package, and composer's extraction phase fills existing vendor/<org>/ directories, so neither a file count nor an mtime moves during the longest stretch of an install. Both read as finished mid-install.

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.

Downloads are disclosed, not started

An assistant is not the one paying for the bandwidth, so the actions that have to fetch a container image (service preset_install, update, migrate, rollback, reinstall, and runtime ext_add, which rebuilds a PHP image) answer with what they would download instead of downloading it. The answer names the image and its size, read from the registry manifest without pulling anything, and nothing has been fetched at that point. Repeating the call with confirm: true goes ahead. An image already in the local store is never disclosed, so the usual case runs straight through. This is the disclosure half of what LERD_OFFLINE=1 does for the refusal half; see Image downloads.

Worker tuning comes from the framework definition

worker list reports each worker's tunable options: the placeholders its framework definition declares in tune_command, the default the definition runs for each, and whatever the project committed to .lerd.yaml. start (and queue_start) take them back as options: ["queue=emails", "tries=5"]. Nothing is named in the tool's own schema, so a store definition that makes another worker tunable reaches an assistant within the day, the same way the CLI grows a flag per placeholder. See Worker options.

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