Mcp Server Bundle Laravel Package

Getting Started

First, a reality check. Despite the "MCP" naming, this is a Symfony bundle, not a Laravel package. There is no service provider, no config/mcp.php, and its entire value proposition is reading data out of Symfony's profiler service and its collector pipeline. If you are a Laravel developer, your realistic relationship to this repo is one of two things:

1. You maintain or consult on a Symfony app and want profiler access for an AI agent — in which case you should now start with Symfony AI Mate instead (see below).
2. You are reading it as a reference implementation for how to wrap framework diagnostic data as MCP tools, to build the Laravel equivalent (Telescope/Debugbar → MCP).

The headline changed in 0.2.1: this bundle is officially deprecated and 0.2.1 is the final release. The maintainers point at Symfony AI Mate, part of the Symfony AI project, as the supported path. The bundle shipped in March 2025, before any official Symfony solution existed — which is why it got its installs and why it is now a dead end.

If you are starting fresh on Symfony, go straight to Mate:

composer require --dev symfony/ai-mate
vendor/bin/mate init
composer require --dev symfony/ai-symfony-mate-extension symfony/ai-monolog-mate-extension
vendor/bin/mate discover

The README lists the Agent Skills that Mate installs for your coding agent. Note the architectural shift: Mate is driven by a vendor/bin/mate CLI plus installed Agent Skills, not by a hand-wired stdio MCP server entry — check the Mate docs for whether/where it still exposes MCP tools if your client depends on that.

If you are inheriting an app already on this bundle, removal is three mechanical steps:

1. composer remove killerwolf/mcp-profiler-bundle
2. Delete its line from config/bundles.php
3. Delete the mcp:server:run entry from your MCP client config

Where to look first (either way): the README for the exact command name and config keys — the command is mcp:server:run, and blog posts frequently get this wrong. Then the console command class (transport/bootstrap), then the classes that map each profiler collector to an MCP tool/resource. That mapping layer is the whole product; everything else is boilerplate.

First use case: "Why is GET /api/orders slow?" Reproduce the request once in a browser or curl so the profiler actually records it, then ask the agent to list recent requests, open the slow token, and pull the query list and timeline. The payoff over pasting a profiler URL is that the agent can iterate: list → drill → correlate queries with timing without you copying screenshots. On Mate, the same loop applies — only the plumbing differs.

Implementation Patterns

Populate-then-query loop. The profiler is a store of past requests, not a live tracer. The working rhythm is: hit the endpoint → let the agent read the recorded token → change code → hit it again → compare. Bake this into your prompts; agents will otherwise ask for profiler data that does not exist yet and conclude the server is broken.

Chain tools, don't dump. The useful call graph is coarse-to-fine: list recent requests → get request by token → get queries for token / get timeline. Ask for "the 5 slowest requests in the last 10 minutes," not "all requests." Context windows die on unfiltered query lists.

One server entry per app. If you run multiple Symfony kernels (monorepo, API + admin), register a separate MCP server entry per project root with its own absolute bin/console path. Relative paths are the number-one cause of "server failed to start" in MCP client logs.

Share the config, not the state. Commit the MCP client snippet (.mcp.json, .cursor/mcp.json, or a docs block) so the whole team gets the same tool wiring. Never commit the profiler storage or anything the server can read — see the PII note below.

Pair with filesystem tools. The profiler tells you what happened (this query ran 40 times, this listener took 300ms); the agent still needs file access to find the listener. Configure both servers; a profiler-only agent can diagnose but not fix.

Use it as an MCP pattern reference for Laravel. The transferable design is: enumerate collectors → expose each as a tool with a small, filtered schema → return compact JSON, not raw collector dumps. If you build a Laravel equivalent over Telescope entries, copy that shape and skip the Symfony plumbing. There is still no official Laravel counterpart to Mate, so this reference value is the main thing left in the repo — read it now, before it bit-rots.

Gotchas and Tips

• Deprecation is the top gotcha, and it is silent. The 0.2.1 notice lives in the README only — there is no runtime trigger_deprecation(), no console warning, and no composer abandoned flag mentioned in the release. Nothing will tell you at install time or boot time that you are adopting a frozen package. Put a migration ticket in the backlog the day you adopt it, and pin the version.
• 0.2.1 makes it easier to adopt by accident. It ships a PHP 8.4 explicit-nullable fix in MCPDataCollector::collect() and restores CI on PHP 8.1–8.4. So it installs cleanly on modern PHP — do not read "it installs" as "it is maintained." The final release is a compatibility patch plus a tombstone, not a revival.
• Empty results are almost always a profiler problem, not an MCP problem. Check: APP_ENV=dev, framework.profiler enabled, a request actually recorded, and that the bundle reads the same profiler storage backend you write to (file vs. SQLite vs. Redis). Mismatched storage is silent and looks like "the server has no data."
• Tokens are ephemeral. Profiler storage gets pruned. A token from yesterday may 404 today; re-request rather than debugging the agent.
• Never write to stdout in the stdio path. JSON-RPC framing breaks on any stray echo, dump(), or deprecation notice printed by a booting kernel. Route logs to stderr and keep APP_DEBUG output out of the transport. This manifests as the client hanging or "invalid JSON" with no useful error.
• Cold start per call. Each invocation boots the Symfony kernel. Long agent sessions with many tool calls get slow; prefer fewer, richer calls.
• Payload bloat. Query lists and timelines are the biggest responses in the system. Cap them in the prompt ("top 10 by duration") rather than hoping the tool paginates.
• Treat the profiler as sensitive. It contains SQL, request bodies, headers, and often credentials or PII. The server runs as your shell user with your filesystem access; do not expose it to a shared or remote agent runtime, and do not let it write outside the project.
• Debug by hand first. Pipe a JSON-RPC initialize and tools/list into php bin/console mcp:server:run directly before blaming the client. That single step separates "server broken" from "client config wrong" in about thirty seconds.
• Extension points: if the tool layer enumerates profiler collectors dynamically, your custom collectors show up for free; if tools are hardcoded per collector, they won't. Verify this before building a custom collector specifically to feed the agent — and remember any collector work you do here has no forward path, so prefer migrating the intent to a Mate extension.
• Laravel developers: do not install this. It has zero Laravel integration and will fail at bundle registration. Read the source, steal the tool-design pattern, and build against Telescope — and if you are evaluating this because a Symfony team asked you to standardise agent tooling, push them to Mate rather than pinning 0.2.1.