Laravel Laravel Package

Getting Started

php-mcp/laravel wires the php-mcp/server core into Laravel so you can expose tools, resources, and prompts to MCP clients (Claude Desktop, Cursor, Zed, custom agents) over stdio or HTTP without hand-rolling JSON-RPC.

1. Install and publish config — composer require php-mcp/laravel, then publish the config/routes the service provider offers (check php artisan list mcp for the package's install/inspect commands). The published config/mcp.php is the source of truth for transport, discovery, and session settings; read it before anything else.
2. Check your versions first (4.0.0) — this is a major bump. Verify your php and laravel/framework constraints in composer.json before upgrading; the release adds Laravel 13 support and, as with any 3.x → 4.x jump, expect minimum-version bumps and possible config/signature changes. Run composer update php-mcp/laravel -W and diff the published config against the new stub.
3. Register a server — create a server definition (usually under app/Mcp or a routes/mcp.php-style file) and attach tools:

   Mcp::server('app')
       ->withTools([LookupOrder::class, SearchDocs::class])
       ->withResources([...])
       ->withPrompts([...]);
   

4. First use case — a single read-only tool is the fastest validation loop. Wrap an existing action or query in a Tool class, point Claude Desktop or Cursor at your endpoint (or your php artisan mcp:serve-style stdio command), and confirm the tool shows up in the client's tool list. That proves discovery, schema generation, and transport in one shot.
5. Upgrade-path extra for 4.0.0 — if you deploy to serverless or multi-instance infra, read the stateless-mode notes below before choosing a transport; it likely simplifies your deployment materially.

Implementation Patterns

Tools as thin adapters over existing application code. Don't put business logic in tool classes. Inject your services/actions and let the tool do argument → DTO → call → response mapping. This keeps tools testable and lets the LLM-facing schema evolve independently of domain code.

Validate and describe explicitly. LLM clients pick tools from names + descriptions + JSON schemas. Name tools as verbs (search_orders, refund_payment), write descriptions for a reader with no context, and use the package's schema/attribute support to mark required fields and enums rather than relying on inference from PHP types alone. Return structured results (arrays/DTOs the package serialises) with a clear error/success shape instead of throwing raw exceptions — the model needs actionable text, not a stack trace.

Split read from write, and gate writes. Read-only tools ship first. For mutating tools, combine three things: an authorisation check inside the tool (the MCP request is still a request — run it through your policies/Gates using the authenticated user, not a service account), idempotency where the operation allows it, and a confirmation-style parameter or two-step tool for destructive actions. Never assume the client will ask the user first.

Transport selection matrix.

• stdio — desktop/local clients, single user, no auth needed. Process is spawned per client session; logs must go to stderr.
• HTTP (session-based) — remote clients, long-lived sessions, server-initiated messages. Requires a shared session/cache store when you run more than one instance.
• HTTP stateless (4.0.0) — one request in, one response out. No session store, no sticky sessions, works behind any load balancer and on Lambda/Vapor/Cloud Run. Choose this as the default for stateless-first deployments where you don't need server-initiated notifications.

Stateless mode in practice. Keep request handling self-contained: no in-memory state between calls, no reliance on progress notifications or resource-subscription updates, and re-resolve the authenticated user from the request each time. Tools should be idempotent or explicitly non-idempotent, and any long-running work should be queued with the tool returning a job/handle the client can poll via a second tool. The stateless flag lives in the transport configuration/registration call — the exact key is in the published config after upgrade.

Testing and CI. Write feature tests that invoke each tool class directly with a constructed request object and assert on the returned payload — fast, no transport needed. Add one integration test per configured transport that boots the server and lists tools, so registration/discovery breakage is caught. Assert on the tool schema too: a renamed parameter is a breaking change for every prompt that used it.

Observability. Log every tool invocation with tool name, argument keys (not raw sensitive values), duration, and outcome, using a dedicated channel. This is your only window into what an agent is doing, and it's what you'll replay when a model starts calling the wrong tool.

Gotchas and Tips

• 4.0.0 is a major, not a patch. "Laravel 13 support" usually ships alongside a raised minimum for PHP/Laravel. Pin ^4.0 deliberately, run your test suite, and re-publish/diff config/mcp.php — a changed default (transport, discovery, middleware group) can silently alter behaviour.
• Session store surprises on HTTP. Session-based HTTP transports need a cache/session driver that supports locks and is shared across instances. A file or array cache driver will look fine locally and fail under load. Stateless mode sidesteps this entirely — often the single best reason to upgrade.
• Stateless ≠ feature parity. Server-initiated capabilities (sampling, elicitation, resource-updated notifications, stream resumption) don't fit a request/response model. Audit any tool that depended on pushing messages to the client before flipping the switch.
• stdout is the wire. Anything echoing to stdout in stdio mode (a stray dump(), dd(), a deprecation notice, a package that echos) corrupts the JSON-RPC stream and produces baffling client errors. Route logs to stderr/files and never leave debugging output in tool code.
• Long tool calls and timeouts. HTTP clients and proxies time out. Keep tool execution fast; offload anything heavy to a queue and return a handle. Stateless deployments have no session to come back to, so design the follow-up tool to be callable independently.
• Authorisation is yours. The package authenticates the transport (middleware, tokens, OAuth if configured) but not your domain rules. Put $this->authorize(...) or a policy check inside every mutating tool — a permissive endpoint exposed to an agent will eventually be asked to do something creative.
• Schema is a public contract. Changing a tool name, description, or parameter breaks clients that cached the old schema. Version tools (search_docs_v2) or keep backwards-compatible aliases during transitions.
• Debugging loop. List the registered tools first (package artisan command / config dump) → confirm the client sees the same list → then check the invocation log → then the tool's response body. If the tool never appears, it's discovery/registration; if it appears but never fires, it's the description or schema; if it fires and returns junk, it's serialisation.
• Extension points to lean on. Publish the config rather than editing vendor defaults; register tools conditionally per environment (e.g. exclude destructive tools outside production); and wrap cross-cutting concerns (audit logging, rate limiting, argument redaction) in a base tool class or middleware rather than repeating them in every tool.
• Upgrade checklist. Composer constraints → re-publish and diff config → run the suite → decide transport (stateless vs session) → verify auth middleware on the new route → smoke-test from a real MCP client, since unit tests won't catch discovery or transport regressions.