Laravel Agentic Laravel Package

Getting Started

• Confirm your app meets the dependency floor introduced in v0.1.1: laravel/mcp ^1.0 and laravel/ai ~0.11.0. This is a compatibility release — the notes explicitly say no source changes are needed — so upgrading from 0.1.0 should be a Composer bump plus a smoke test.
• Install/upgrade with Composer, then publish any package config if you have not already. Review the config for where actions are registered and which MCP server/transport is exposed.
• Start with one existing action rather than a full tool catalogue. Expose a single read-only action, start the MCP server using the command provided by laravel/mcp, and connect a client (MCP inspector, Claude Desktop, Cursor, or an agent built with laravel/ai).
• Look first at the raw tools/list response. In v0.1.1 each tool should have a name derived from the action (e.g. refund-invoice) and a title derived via Str::headline() (e.g. Refund Invoice). If you still see “Action Tool”, you are on the old version or hitting a cached server.
• First useful use case: wrap a low-risk internal action such as “look up invoice” or “summarise ticket”, call it from an MCP client, then iterate on schema, validation, and error responses before exposing mutating actions.

Implementation Patterns

• Treat each action as one MCP tool. Keep the action focused, give it a clear snake/kebab-case name, and let the package derive the display title. The tool name is the contract clients call; the title is presentation metadata.
• Define explicit input schemas and validate inside the action with Laravel validation. MCP clients and LLM agents will send loosely typed arguments; reject bad input early and return structured, JSON-serialisable errors.
• Separate read-only tools from mutating tools. For writes, make actions idempotent where possible, return the affected resource ID, and log the caller/request context so you can audit agent-initiated changes.
• Register tools close to your domain code or in a dedicated MCP service provider, and group related actions (billing, support, reporting) so tools/list stays navigable for both humans and agents.
• Use the package alongside laravel/ai agents: let the agent discover tools via tools/list, then invoke them through tools/call. Because v0.1.1 supports MCP protocol 2026-07-28 plus legacy initialize clients, test the specific client you use rather than assuming compatibility.
• In CI, snapshot the tools/list output (names, titles, input schemas) and fail on unexpected changes. This catches accidental tool renames and title regressions before clients break.
• For local development, inspect the JSON-RPC traffic directly and keep the MCP server logs visible. A quick manual tools/list followed by a tools/call against a staging action is the fastest end-to-end check after a dependency bump.

Gotchas and Tips

• The title is cosmetic and derived with Str::headline(). Do not build routing, permissions, or client logic on the title — use the tool name. Renaming an action changes both the name and the title, and clients may cache tool names across sessions.
• Str::headline() can produce surprising casing for acronyms and domain terms (refund-invoice → Refund Invoice, but vat-refund may not read the way you want). If precise display titles matter, check whether the package exposes an override; otherwise this is a good extension-point/PR candidate.
• The laravel/mcp jump from ~0.9.0 to ^1.0 is the significant part of this release. The new server advertises protocol 2026-07-28 and still supports legacy initialize clients, but verify older MCP clients and any custom JSON-RPC handling against the new protocol.
• laravel/ai ~0.11.0 is also a minor-version bump. Although the release notes say no source changes are needed, skim its changelog for agent/tool-calling API adjustments before upgrading a production agent.
• Authorisation is your responsibility. An MCP server can be reachable by any connected client, so enforce policies inside the action (Gate/Policy checks, tenant scoping) rather than relying on the transport being private.
• If a client shows a generic “Action Tool” label, confirm the installed package version, restart the MCP server, and re-read tools/list. Stale server processes and cached client tool lists are common causes.
• Prefer structured error results over thrown exceptions for expected validation failures; MCP clients and LLM agents usually surface structured content more reliably than stack traces.