Nova Mcp Laravel Package

Getting Started

Requirements first. v0.2.0 is a hard break from earlier setups: PHP 8.3+, Laravel 12 or 13 (Laravel 11 is gone), a licensed Laravel Nova 5 install, and Laravel MCP 1.x. Laravel AI is optional — only pull it in if you intend to use the AI SDK adapter.

composer require davidhemphill/nova-mcp
php artisan vendor:publish --tag="nova-mcp-config"

Where to look first, in order:

1. The published config file — it controls server naming, tool exposure, and which Nova resources are surfaced.
2. The MCP server registration in routes/ai.php (or wherever your app registers MCP servers) — confirm the package server is registered and reachable.
3. The package's own feature suite. With 59 tests / 187 assertions across six Laravel × PHP combinations, the tests are the most reliable documentation of intended tool shapes, especially the Laravel AI adapter test.

First use case: expose one Nova resource as a read-only MCP tool and confirm the round trip before touching anything write-capable. Point an MCP client at your server (MCP Inspector is the fastest), verify the tool appears in the discovery listing, then make a single call against a record you can eyeball in Nova. Getting listing-then-call working end to end proves the protocol negotiation, auth, and Nova policy wiring all at once — which is exactly the surface that changed in this release.

Implementation Patterns

Thin tools over Nova, not parallel logic. The value of this package is that MCP tools reuse your existing Nova resources, fields, and policies. Resist the urge to hand-roll query logic inside a tool; if a tool needs to behave differently from the Nova UI, express that as a Nova field or policy change so both surfaces stay consistent.

Granularity: one tool per verb per resource. Distinct list, get, and (where justified) create/update tools give the model clearer affordances than a single polymorphic tool with an action parameter. Nova Actions map naturally onto tool-per-operation — especially for privileged or destructive work, where a dedicated, explicitly named tool is easier to gate and audit.

Treat Nova Actions as the write surface. Read endpoints are low risk and easy to ship first. For mutations, route through Nova Actions so you inherit their authorization and audit behavior rather than inventing a second permission model. Name destructive tools unambiguously (delete_invoice, not invoice_manage) — the model picks tools by name.

Keep the AI adapter a second consumer, not a second implementation. The verified Laravel AI v1.2.3 path executes a Nova catalog tool through the AI SDK adapter. Structure tool definitions so the same schema and handler serve both the raw MCP transport and the AI SDK path; if you find yourself maintaining two tool classes for one Nova resource, the abstraction is wrong.

Validate with your own CI matrix. Mirror upstream: Laravel 12 and 13, PHP 8.3 / 8.4 / 8.5. The combination most likely to bite you is Laravel 13 on PHP 8.5, since that's the newest cell in the matrix and the least exercised in the wild.

Test with in-memory Nova auth. v0.2.0 added in-memory Nova package authentication to its test harness specifically so the suite runs without a live license handshake. Copy that approach — don't put real Nova credentials in CI.

Gotchas and Tips

Upgrade order matters. Laravel 11 → 12/13 first, then Laravel MCP 0.9 → 1.x, then this package. Attempting the package bump while still on MCP 0.9 will resolve to a confusing dependency conflict rather than a clear error.

Protocol negotiation is the silent failure mode. This release covers the current MCP discovery protocol while retaining legacy initialization. If a client is pinned to an older handshake, the symptom is usually an empty tool list rather than an exception — check discovery before you debug your Nova policies.

Authorization must filter the schema, not just the call. Nova hides fields the current user can't see. If you build MCP input/output schemas from raw resource definitions before policy filtering, tool descriptions can leak the existence and shape of fields the user shouldn't know about. Build schemas from the authorized view.

Don't require Laravel AI. It's optional in the manifest. Adding it unconditionally bloats installs and can drag in version constraints you don't need; the adapter test simply won't run without it, which is fine.

Cap index payloads. Nova resource indexes are designed for paginated UIs, not context windows. A list tool that returns everything will blow past sensible token budgets — set explicit limits and return truncated summaries with an identifier the model can use to call get.

Extension points worth knowing: published config for server/tool exposure, tool naming and description overrides (descriptions are prompt surface — tune them and measure), and registration of custom tools that aren't derived from Nova resources at all. That last one is your escape hatch when a capability has no Nova analogue.