Minimal working Magento Bricklayer setup

Just enough setup to give Your AI coding agent runtime visibility into Magento 2.

AI agents are good at reading source files, but in Magento the source files only tell half of the story. DI preferences, plugin chains, EAV attributes and event observers are resolved at runtime, across dozens of modules. An agent looking at one module sees only that module’s perspective. It misses overrides and conflicts coming from everything else that is installed, so it guesses.

Magento Bricklayer fixes that. It is a Composer library that implements an MCP (Model Context Protocol) server for Magento 2. Once started, it exposes 84 tools that Your agent can call to check the real runtime state before it writes a single line of code. Only 17 essential tools are visible at startup, the remaining 67 are discoverable via search-tools, so the agent does not burn tokens on tool definitions it does not need.

It is not a Magento module. Same idea as n98-magerun2: no module registration, no setup:upgrade, no database cleanup when You remove it.

Requirements and installation

Let’s assume we have a working Magento 2 instance with:

  • PHP 8.3 or higher
  • Magento 2.4.7 or higher
  • Composer 2.2 or higher

Install it as a development dependency (recommended):

composer require --dev inchoo/magento-bricklayer

If You prefer it available everywhere, global install works too:

composer global require inchoo/magento-bricklayer

Generate agent configuration

Run from Your Magento project root:

vendor/bin/bricklayer install

It asks which AI agents You use and generates:

  • .mcp.json - MCP server configuration (always created)
  • .bricklayer.json - tool safety configuration with deploy-mode-aware defaults
  • agent-specific guideline file, depending on Your selection
Agent Guideline file
Claude Code CLAUDE.md
Cursor .cursorrules
GitHub Copilot .github/copilot-instructions.md
JetBrains AI (PhpStorm) .junie/guidelines.md
Gemini CLI AGENTS.md
OpenAI Codex AGENTS.md (+ .codex/config.toml instead of .mcp.json)
Mistral Vibe AGENTS.md (+ .vibe/config.toml instead of .mcp.json)

No need to start the MCP server Yourself, compatible agents start it automatically (vendor/bin/bricklayer mcp).

If You are running Magento in Docker, DDEV or Warden, install detects it and writes the correct command into .mcp.json:

# Docker Compose
docker compose exec -T php php vendor/bin/bricklayer-mcp

# DDEV
ddev exec php vendor/bin/bricklayer-mcp

# Warden
warden shell -c php vendor/bin/bricklayer-mcp

Container names that change between environments? Point .mcp.json to the wrapper script, it finds the PHP container at runtime:

{
    "mcpServers": {
        "magento-bricklayer": {
            "command": "vendor/inchoo/magento-bricklayer/bin/bricklayer-mcp-docker",
            "args": []
        }
    }
}

Tool safety: .bricklayer.json

Giving an AI agent access to a live Magento instance sounds scary, so Bricklayer ships with safe defaults that depend on Your deploy mode:

  • developer/default - 11 destructive tools (*-delete, order-cancel, order-create, creditmemo-create, 4 generate-*) are disabled, everything else is enabled, code-runner is read-only
  • production - same 11 tools plus code-runner disabled, database-query.max_rows lowered to 50

Generated developer-mode config, excerpt:

{
    "tools": {
        "code-runner": {
            "enabled": true,
            "allow_write": false,
            "max_timeout": 60
        },
        "database-query": {
            "enabled": true,
            "max_rows": 100
        },
        "product-delete": { "enabled": false },
        "order-cancel": { "enabled": false },
        "generate-module": { "enabled": false }
    }
}

No need to memorize keys, change values with config:set (interactive, or scripted with dot-notation):

vendor/bin/bricklayer config:set
vendor/bin/bricklayer config:set tools.product-delete.enabled true
vendor/bin/bricklayer config:set tools.database-query.max_rows 250

The running MCP server picks up the change on the next tool call, no agent restart needed. Same goes for Magento itself: after setup:upgrade or setup:di:compile, Bricklayer notices and reinitializes its ObjectManager automatically.

Few more things worth knowing:

  • database-query is SELECT only, with automatic LIMIT
  • sensitive config values (payment/*, carriers/*, oauth/*…) are masked in results
  • code-runner rolls back DB changes unless allow_write=true, and it can not be enabled in production under any circumstances
  • code generation writes only to app/code and app/design
  • every setting can be overridden with an env variable, e.g. BRICKLAYER_TOOLS_CODE_RUNNER_ENABLED=false

What Your agent gets

The idea is simple: check -> learn -> write. Every tool response includes a hint pointing to the next logical step, so the agent naturally follows that flow.

  • Before writing a plugin - check-class returns existing plugins with their sortOrders, DI preferences and rewrites for a class in one call. No more conflicts that show up only on a store with 30 more extensions installed.
  • Before touching products or customers - eav-attributes lists custom attributes that exist only in the database, not in any source file.
  • When debugging - diagnose-error combines the exception log, stack trace, DI context and plugin chains into one diagnosis with fix suggestions. Much more than tail var/log/exception.log.
  • Before writing any code - development-context loads guidelines for the task at hand (38 categories: plugins, EAV, GraphQL, Hyvä, Magewire, checkout, payment, testing…).

And the rest of the toolbox, grouped:

  • application and modules: application-info, module-list, module-structure, validate-module
  • database: database-schema, database-query
  • config and DI: configuration-get, di-configuration, plugin-list, preference-list, event-list
  • routing and APIs: route-list, api-endpoints, url-rewrites, graphql-inspect
  • view: layout-inspect, ui-component-inspect
  • message queues: message-queue-inspect
  • catalog, orders, customers: full CRUD through Magento’s service layer
  • system: system-status, diagnose-performance, log, code-runner
  • code generation: generate-module, generate-model, generate-controller, generate-api (with dry_run)

Project has its own conventions? Drop markdown files into .bricklayer/ (guidelines, skills, project-context.md) and run vendor/bin/bricklayer update, they get compiled into the agent files without forking the package.

Verify and start

Run the health check:

vendor/bin/bricklayer verify

It checks Magento bootstrap, deploy mode detection, MCP server creation and tool count, agent config files, PsySH availability for code-runner, database connectivity, log directory permissions and .bricklayer.json validity. If .bricklayer.json is missing, it generates one.

  • If You are working in git flow, add .mcp.json, .bricklayer.json and Your agent file to the commit, so the whole team gets the same setup
  • Done with it? composer remove inchoo/magento-bricklayer, nothing to clean up in the database

Your final project root (Claude Code selected) should look like this:

magento-root/
├── .bricklayer/          # optional, project-local overrides
├── .bricklayer.json
├── .mcp.json
├── CLAUDE.md
├── app/
├── composer.json
└── vendor/
    └── inchoo/
        └── magento-bricklayer/

Start coding! Or better, let Your agent start, now it knows what it is working with.

Source: GitHub · Packagist