Ranetrace Laravel Laravel Package

Getting Started

1. composer require ranetrace/ranetrace-laravel — the service provider auto-registers, so exception/telemetry capture starts working as soon as credentials are present.
2. Publish the config (php artisan vendor:publish and pick the Ranetrace provider) and set the API key from your website's Ranetrace project settings in .env. Everything else in config/ranetrace.php has a sane default.
3. Verify wiring with the two artisan commands before touching any code: php artisan ranetrace:test (send a known event round-trip) and php artisan ranetrace:status (what the package thinks it is configured to do). If those two are green, your problem is in ingest/queue, not config.
4. Open the diagnostics dashboard route shipped by the package to see the same picture in the browser — useful for non-terminal teammates.

First real use case: instrument one noisy endpoint, not the whole app. Let the package capture it, then have an agent investigate the resulting errors through the hosted MCP server — no local server, no package-side runtime, no laravel/mcp dependency.

MCP setup (v1.1.1+, two steps, client-side only):

claude mcp add --transport http ranetrace https://api.ranetrace.com/mcp --header "Authorization: Bearer <token>"

Create the token on your website's /mcp page in Ranetrace. File-configured clients (Cursor, VS Code) use the same URL and header under an mcpServers entry with "type": "http".

Upgrading from ≤1.1.0: delete RANETRACE_MCP_ENABLED and RANETRACE_MCP_TOKEN from .env, remove the ranetrace.mcp config block if you had published and edited it, and drop laravel/mcp from your app if nothing else needs it. Tool names, parameters and output are unchanged — only the transport moved from local stdio to Streamable HTTP.

Implementation Patterns

Treat the package as two independent surfaces. Ingest (app → Ranetrace) and MCP (agent → Ranetrace) no longer share a process, a config block, or a lifecycle. Tune them separately; a change to one should never require redeploying for the other.

Batch ingest is the stable contract. The five batch ingest methods and everything the batch worker touches are explicitly unchanged across this release. If you have custom batching, queue tuning, or a worker supervisor tuned around them, leave it alone — this is the part of the package to build on confidently.

Agent-driven debugging loop. Reproduce or triage in the dashboard, then hand the agent a task against the 31 hosted tools ("list unresolved errors for the checkout route since the last deploy, group by message"). Because tool names and output are identical to the old local server, any saved prompts, tool allowlists, or agent instructions you wrote for 1.1.0 keep working verbatim.

One token per website per environment. Create tokens on each website's /mcp page and use distinct tokens for staging and production. Keep them in your secret store / CI variables — never in a committed mcp.json. Rotating a leaked token is a dashboard action, not a code change.

Shared team config. Commit a project-level MCP config that references an env var for the token ("Authorization": "Bearer ${RANETRACE_TOKEN}" where the client supports interpolation) so onboarding is "install client, set one variable."

Deploy-pipeline usage. Run ranetrace:status as a post-deploy smoke check — it exits with a signal if the package is misconfigured. Pair it with a ranetrace:test in staging only, so you don't pollute production error streams with synthetic events.

Diagnostics as a boundary. Keep MCP out of your operational checks entirely now. The MCP rows were removed from the diagnostics dashboard, ranetrace:status and ranetrace:test; verify MCP connectivity from the client (claude mcp list, or a trivial tool call), never from your app.

Gotchas and Tips

• Breaking removal shipped in a patch. The 1.1.0 deprecation note promised removal "in the next major"; it landed in 1.1.1. Don't assume semver comfort from this package — read the changelog on every update, and consider exact version pins in composer.json if you can't tolerate surprise breaks.
• Silent env var death. RANETRACE_MCP_ENABLED and RANETRACE_MCP_TOKEN are no longer read anywhere. They won't warn — they'll just do nothing. Stale copies in .env, .env.example, Dockerfiles, or CI secrets are a classic source of "why isn't this working" confusion. Grep for RANETRACE_MCP across the whole repo and infra config, not just .env.
• Absent MCP output is not a failure. If your runbook says "check MCP status in ranetrace:status," that line is now dead. Update the runbook; the commands no longer report on MCP at all.
• laravel/mcp is now orphaned. It left the package's dependencies. If your app pulled it in transitively, composer why laravel/mcp and remove it explicitly — leftover copies are dead weight and a confusing signal during upgrades.
• 401s are a token problem, not a code problem. Wrong website's token, rotated token, or a missing Authorization header on a per-request basis. The header must be on every request; some file-based client configs drop unknown keys silently.
• The endpoint is remote — egress matters. Firewalled CI, locked-down containers, or corporate proxies that reached the old local server will now fail. Test from the actual environment that runs the agent, and check DNS/TLS to api.ranetrace.com before debugging the token.
• No local logs to tail. Debugging MCP is no longer tail on an app log. Troubleshooting is client-side: verbose client logs, plus a minimal tool call to isolate auth from tooling.
• Extension points didn't move, but MCP-adjacent ones vanished. The API client's MCP read methods are gone. If you subclassed or called them, migrate to calling Ranetrace over HTTP yourself — that surface is no longer the package's responsibility.
• Single-consumer package. The maintainer states this package has one consumer and made a deliberate semver break. Optimize for fast, frequent, small updates over long-lived forks; resist deep customization of internals that can be deleted in a patch.