Laravel Agentic Laravel Package

Product Decisions This Supports

• Agent/tooling surface strategy. This package is a thin adapter that turns existing laravel/ai actions into MCP tools, which decides how we expose product capability to agents (Claude Desktop, IDE copilots, internal agent platforms) without building a bespoke tool registry, JSON-schema serializer, and transport layer. It is the cheapest path to "our app is an MCP server."
• Build vs. buy. The alternative is hand-rolling tools/list and tools/call handlers per action, including input schema generation, error mapping, and protocol negotiation. At v0.1.x this package is a build-vs-buy decision weighted toward buy, with the caveat that we are buying a pre-1.0 abstraction over two pre-1.0 first-party dependencies.
• Feature scoping — which actions become tools. Because tools are derived from action names, the decision of "what do we expose to agents" collapses into "which actions do we write." That lowers the cost of shipping an agent-callable feature from weeks to days, and shifts roadmap planning toward a tool catalog rather than endpoint work.
• Client compatibility commitments. The laravel/mcp bump to ^1.0 means the server negotiates protocol 2026-07-28 while still serving legacy initialize clients. That directly determines which MCP clients we can claim support for in docs, sales collateral, and support SLAs — we should state "current + legacy clients" as an explicit promise rather than let it be implicit.
• Discoverability / UX of the tool surface. The title fix (refund-invoice → Refund Invoice) is not cosmetic. MCP client UIs surface tool titles to humans, and model tool-selection quality degrades when every tool is labelled "Action Tool." This makes naming conventions for actions a product decision, not just a code convention.
• Use cases this unlocks now: support/ops actions (refunds, order lookups, ticket triage) invoked from a chat client; internal read-only tooling for non-engineers; developer-facing utilities surfaced in IDEs. Use cases it does not yet unlock without additional work: multi-tenant tool scoping, per-user authorization on tool invocation, high-cardinality tool catalogs.

When to Consider This Package

Consider it when:

• You are already (or are willing to be) on laravel/ai actions as your unit of AI-callable capability — this package's value is proportional to how much logic already lives there.
• You want an MCP-compatible server endpoint in a Laravel app quickly, with a small-to-moderate tool surface (roughly dozens, not hundreds, of tools).
• You can accept pre-1.0 churn: v0.1.1 required no source changes, but two dependency majors/minors landed in a single patch release. Budget for reading release notes on every bump.
• You need legacy-client compatibility; the ^1.0 line covers both the new protocol and initialize clients, so you do not have to choose.
• Your actions are reasonably self-describing by name, since titles and (presumably) tool identity derive from the action name.

Look elsewhere when:

• You need stable, versioned public API guarantees or a deprecation policy — there is none at 0.1.x.
• You need per-tool or per-tenant authorization, rate limiting, audit trails on tool invocation, or multi-tenant tool partitioning. Plan to build this yourself around the package, or evaluate laravel/mcp directly so you control the handler layer.
• Your capabilities are not modelled as laravel/ai actions. In that case the adapter is pure overhead; use laravel/mcp directly.
• You have a large or dynamic tool catalog requiring search, pagination, or runtime registration — the "derive tools from actions" model is a compile-time-ish approach and will strain.
• You need transports, streaming semantics, or protocol features the underlying laravel/mcp release does not cover — verify against your client matrix before committing.

How to Pitch It (Stakeholders)

To executives: This is a low-cost adapter, not a platform. It lets our existing AI actions be called as tools by agent clients — Claude Desktop, IDE assistants, internal agent tooling — through the Model Context Protocol, which is becoming the default way agent products discover capability. The commercial upside is that our product becomes invocable inside the tools customers already use, rather than requiring them to come to our UI. The cost is small and mostly configuration; the main risk is that it sits on two fast-moving, pre-1.0 Laravel packages, so we should treat it as a time-boxed bet with an exit to laravel/mcp directly if the abstraction stops earning its keep.

To engineering: v0.1.1 is a strict improvement with no source changes on our side — two Composer constraint bumps (laravel/mcp ^1.0, laravel/ai ~0.11.0) plus a fix that gives every tool a human-readable title derived via Str::headline(). Practical consequence: we now serve protocol 2026-07-28 with continued support for legacy initialize clients, so client-version support widens for free. Action names are now part of the public tool surface — treat naming as an interface decision, use kebab-case verbs, and avoid renames without a deprecation path, since names appear verbatim in client UIs and drive model tool selection. Adoption is a Composer bump plus a review of your action naming; the one thing worth a spike is authorization on tools/call, which the package does not appear to own.