Workflows

Codex

Codex can use the same local MCP server as the Claude Code plugin. Codex runs scans, explains findings, fixes the ones that belong to your change, creates baselines and reads Cloud report history. The server runs on your machine and needs no account.

Requirements

PHP 8.2 or newer available as php
A Laravel 12 or 13 application with LaraBeacon Core installed. Without it, the server starts and explains the installation. The Cloud tools need Core 3.3 or newer.
Codex opened in the Laravel project root. Tested with the Codex CLI; see Project root if the IDE extension or the app starts in another folder.

1. Download the server

The server is a dependency-free PHP script in the public plugin repository. Clone it once to a permanent location:

git clone https://github.com/Baer-Software/larabeacon-claude-plugin.git ~/.codex/larabeacon

2. Add it to Codex

Add this block to ~/.codex/config.toml, or to .codex/config.toml in a single project. Use the absolute path to your home directory, because the file does not expand ~.

[mcp_servers.larabeacon]
command = "php"
args = ["/Users/you/.codex/larabeacon/server/larabeacon-mcp.php"]
tool_timeout_sec = 660

tool_timeout_sec matters: Codex stops a tool after 60 seconds by default, and a full scan of a larger application can take longer. The server ends a run after 600 seconds itself, so the slightly higher value lets you see its own timeout message.

Start Codex in the Laravel project root and check the connection with /mcp. Then ask, for example, “Is this project ready for production? Use LaraBeacon.”

Tools

Tool	What it does	Changes files
`larabeacon_status`	Laravel, Core and Pro versions, available updates, Cloud configuration and next steps	No
`larabeacon_scan`	Runs `php artisan larabeacon` with a profile, selected checks, baseline and fix previews	No
`larabeacon_preflight`	Describes the environment and the checks a profile would run	No
`larabeacon_checks`	Searches the Core and Pro check catalogue	No
`larabeacon_baseline`	Writes a JSON acceptance baseline with a required reason	One file
`larabeacon_update`	Updates LaraBeacon with Composer within your `composer.json` constraints	`composer.lock`
`larabeacon_cloud_upload`, `larabeacon_cloud_reports`, `larabeacon_cloud_report`	Upload a scan on request and read the project’s Cloud report history	No

Codex asks before tool calls according to your approval settings. To approve read-only tools automatically and confirm the rest, add default_tools_approval_mode = "writes" to the block above.

With LARABEACON_AUTO_UPDATE=1, the first status or scan of a session may run composer update for LaraBeacon and change composer.lock; both tools are then no longer marked read-only, so Codex asks before running them.

Settings

Codex does not pass your shell environment to MCP servers. Set LaraBeacon’s variables in an env table of the same server block:

[mcp_servers.larabeacon.env]
LARABEACON_UPDATE_CHECK = "0"   # never ask Packagist for a newer release
LARABEACON_AUTO_UPDATE = "1"    # optional: update LaraBeacon without asking
LARABEACON_MCP_TIMEOUT = "600"  # seconds per Artisan or Composer run

Project root

The server works in the folder Codex starts it in and walks up to the nearest Laravel root. If the tools report that no Laravel application was found, set the folder explicitly in the project’s .codex/config.toml:

[mcp_servers.larabeacon]
command = "php"
args = ["/Users/you/.codex/larabeacon/server/larabeacon-mcp.php", "--project=/Users/you/Sites/my-app"]
tool_timeout_sec = 660

Data boundary

The server runs locally and starts php artisan and composer in your project without a shell. It never reads .env or Cloud tokens and collects no telemetry. The vulnerable-dependency checks run composer audit and npm, pnpm or yarn audit, which send package names and versions to Packagist and the npm or Yarn registry. larabeacon_status asks Packagist for the newest LaraBeacon release at most once a day; disable it with LARABEACON_UPDATE_CHECK = "0" in the server’s env table. Only larabeacon_cloud_upload sends a report, with the same payload and opt-ins as --report.

Finding text comes from your project. The server marks it as data, so Codex does not treat it as instructions.

Updates

Pull the repository to update the server; Codex starts the new version in the next session:

git -C ~/.codex/larabeacon pull

LaraBeacon Core itself is updated in your project. larabeacon_status reports a newer release, and larabeacon_update applies it after you agree.

Laravel Boost

If the project uses Laravel Boost with Codex selected as an agent, php artisan boost:update adds LaraBeacon’s guidelines and release-check skill for Codex; to add Codex as an agent, run php artisan boost:install again and select it. The MCP server and Boost complement each other: Boost tells Codex when to check, and the server runs the scan with structured results.

RelatedClaude Code plugin