Connect New Debug Bar to Codex, Claude, Cursor, or VS Code

Before you start

Install New Debug Bar in your Laravel app.
Make sure the app uses its local environment.
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.

Codex

The optional New Debug Bar plugin 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.

For manual setup, add a project-specific server 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"
      ]
    }
  }
}

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"
      ]
    }
  }
}

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-section
get-debug-profile-data
inspect-debug-queries
get-debug-findings

Visit a page in your Laravel app, then ask:

Debug one request with an agent

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.
Read findings first

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

Use the symptom to choose Queries, Exceptions, Timeline, HTTP client, Livewire, Queue, or another small section instead of dumping the full profile.
Follow deeper paths only when needed

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

Troubleshooting

The server is missing

Make sure the package is installed, the app uses an allowed local environment, and NEWDEBUGBAR_ENABLED is not set to false.

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

Visit a normal page in the Laravel app first, then ask the client to list recent profiles again.

The client only runs online

New Debug Bar needs a local MCP client that can start a command on your computer.