Use with agents

Connect The New Debug Bar to your coding agent

Let Codex, Claude Code, Cursor, VS Code, or another local MCP client read the exact profile saved for each Laravel request.

  1. Laravel app

    Capture the local request you want the agent to investigate.

  2. Local MCP server

    The coding client starts this app’s Artisan command and reads its saved profiles.

  3. Agent workflow

    Use exact evidence to make a focused change and verify the same behavior.
Client setup connects the data. The debugging walkthrough shows how to use it.

Before you start

  • Install The New Debug Bar in your Laravel app.
  • Make sure the app is in an allowed environment, which defaults to local, and The New Debug Bar is enabled. It follows APP_DEBUG unless NEWDEBUGBAR_ENABLED overrides it.
  • For manual setup, find the full path to the app's artisan file.

The examples use /absolute/path/to/your-app/artisan. Replace it with your real path.

The command must boot the same Laravel app and read the same profile storage as the process handling your requests. If the app runs in Sail, Docker, or another host, follow the local environment guide.

Codex

The optional plugin for The New Debug Bar is the simplest setup. It adds product guidance and starts the MCP server from the Laravel app you have open.

codex plugin marketplace add newdebugbar/newdebugbar codex plugin add newdebugbar@newdebugbar

Open the Laravel app's root folder in Codex and start a new task. You do not need to publish The New Debug Bar config file.

If your Codex version does not provide the plugin commands, use the manual MCP setup below.

For manual setup, add a server that points to this app and then check it:

codex mcp add my-app-debug-bar -- php /absolute/path/to/your-app/artisan mcp:start newdebugbar

codex mcp list

Claude Code

Run this command from your project. Local scope keeps the server private to you and this app.

claude mcp add --scope local --transport stdio newdebugbar -- php /absolute/path/to/your-app/artisan mcp:start newdebugbar

Check it with claude mcp list.

Cursor

Create .cursor/mcp.json in your project:

{ "mcpServers": { "newdebugbar": { "command": "php", "args": [ "/absolute/path/to/your-app/artisan", "mcp:start", "newdebugbar" ] } } }

Save the file and restart Cursor. Check the server in Customize → MCPs.

VS Code

Create .vscode/mcp.json in your project:

{ "servers": { "newdebugbar": { "type": "stdio", "command": "php", "args": [ "/absolute/path/to/your-app/artisan", "mcp:start", "newdebugbar" ] } } }

Run MCP: List Servers from the Command Palette to start the server or inspect its output.

Other MCP clients

Add a local stdio server with this command and these arguments. Your client may store this setting in a different file.

{ "command": "php", "args": [ "/absolute/path/to/your-app/artisan", "mcp:start", "newdebugbar" ] }

Check the connection

Your coding tool should show these five read-only tools:

  • list-debug-profiles
  • get-debug-profile-inspector
  • get-debug-profile-data
  • inspect-debug-queries
  • get-debug-findings

Make a request to your Laravel app, using a browser or an HTTP client. For a page you just visited, ask:

Debug one request with an agent

  1. Identify the exact profile

    Give the agent the X-NewDebugBar-Profile response-header value when possible. Otherwise, have it match method, path, status, request type, and recorded time from the recent list.

  2. Read findings first

    Ask what happened, what deserves attention, why it matters, and which retained evidence supports that lead.

  3. Open one focused inspector

    Use the symptom to choose Queries, Exceptions, Timeline, HTTP client, Livewire, Queue, or another small inspector instead of dumping the full profile.

  4. Follow deeper paths only when needed

    Use get-debug-profile-data with /inspectors and returned JSON Pointer paths to reach retained evidence omitted from a concise response.

Profile an API without a browser

The New Debug Bar captures requests inside Laravel. The local MCP server reads those saved profiles, so it works with JSON APIs even when there is no page or visible toolbar. Install and enable the package in the app as usual; the API does not need a separate collector.

  1. Send the API request

    Use curl, Postman, a test, or your agent’s HTTP tools. Use the endpoint’s usual authentication and, where required, session cookies and CSRF token.

  2. Keep the response profile ID

    Read X-NewDebugBar-Profile from that response. The JSON body keeps its normal format, including validation and error responses.

  3. Inspect that profile through MCP

    Start with get-debug-findings, then use a focused inspector or get-debug-profile-data for the evidence you need. MCP reads the result; it does not call the endpoint.
curl -i -H 'Accept: application/json' http://your-app.test/api/trips

Replace the URL with an existing local endpoint. To have an agent compare requests, use a prompt such as:

Profile GET http://your-app.test/api/trips using an HTTP client and The New Debug Bar MCP server. Keep the exact X-NewDebugBar-Profile ID from each response. Compare repeated requests with the same inputs and authentication, separating cold and warm caches. Report status, server duration, query count and time, and peak memory. Inspect findings and the relevant queries, cache activity, or outgoing HTTP calls to explain the expensive work.

A browser is useful for reproducing a real click, fetch, or Livewire interaction. Each resulting HTTP request has its own profile. Fetching the initial HTML with curl does not run its JavaScript or trigger later updates. The request picker lets you inspect calls made by the page.

Troubleshooting

The server is missing
Make sure the package is installed and the app uses an allowed local environment. The package follows APP_DEBUG by default; an explicit NEWDEBUGBAR_ENABLED=true enables it even when debug mode is off, and NEWDEBUGBAR_ENABLED=false disables it.
The command cannot find PHP
Replace php with the full path to your PHP program.
The wrong Laravel app opens
Check that the configured path points to that app's artisan file.
No profiles appear
Make a fresh page or API request with The New Debug Bar enabled, then use its response-header profile ID. Check that the MCP process reads the same app’s profile storage. Stored profiles can expire or be removed by the retention limit.
The client only runs online
This package registers a stdio server, not a remote HTTP MCP endpoint. Your client must be able to launch the Artisan command in an environment that can boot the app and read its profiles. A hosted client that only accepts remote HTTP servers cannot connect directly.

Continue from connection to a verified fix

Use Debug with an agent for a complete repeated-query investigation, including the code change and the check afterward. Use the MCP tool reference for exact inputs, paths, cursors, defaults, and errors.

For host PHP, Sail, Docker, and worker context, use Local environments. For startup errors or missing tools, use MCP troubleshooting.

Client documentation

The commands above start the same local stdio server. Client configuration and management details are documented by OpenAI, Claude Code, Cursor, and VS Code.