Nova Mcp Laravel Package

Getting Started

1. composer require opscale-co/nova-mcp and let Laravel auto-discover the service provider.
2. Publish the config (php artisan vendor:publish --tag=nova-mcp-config or similar — check the package's README for the exact tag) so you get the server name, route prefix, and middleware settings into config/nova-mcp.php.
3. Register the MCP server in your MCP client (Claude Desktop, Cursor, VS Code, or the mcp-inspector) pointing at the package's HTTP endpoint — typically /nova-mcp or whatever you set as the prefix. If the transport is stdio in your setup, use the artisan command the package ships instead of the HTTP route.
4. First use case: expose a single low-risk Nova resource (e.g. a read-only Article or Ticket resource) and ask the model "list the 5 most recent tickets". This validates auth, routing, and schema generation end-to-end before you widen the surface.

Look first at the package's config/ file and its src/Tools (or equivalent) directory — that's where resource-to-tool mapping lives, and it tells you more about behaviour than the README does.

Implementation Patterns

Resource-driven tools. The common pattern is that each Nova resource you opt in becomes an MCP tool with CRUD-ish operations derived from its fields. Start by whitelisting resources explicitly rather than exposing everything Nova knows about — the default surface for a mature app is far too large for a model to choose well from.

Per-resource customisation. Where a resource needs a narrowed tool, override the generated schema or add a dedicated tool class. Good candidates: strip internal fields (tenant_id, audit columns), rename operations to intent-shaped verbs (close_ticket rather than update with a status field), and hard-code filters the model shouldn't be able to change.

Prompts (new in 1.2.0). The release adds a prompts resolver, so you can now ship prompt templates alongside tools. This is the pattern worth adopting immediately: rather than relying on the user to phrase "summarise open tickets older than 7 days" well, register a named prompt with that instruction and the expected arguments. Implement a resolver that returns your prompts (name, description, arguments, and the rendered messages), and keep them next to the tools they drive so a change to a tool's schema and its prompt ship together. Treat prompts as versioned product surface — they're user-facing strings, not internal glue.

Auth and scoping. In practice you want the MCP endpoint behind your normal auth stack (Sanctum token or session middleware), and you want the token to determine which Nova resources are visible. Don't rely on the model to respect tenancy; enforce it in the tool layer so a prompt-injected request can't cross boundaries.

Local vs production. Run against a seeded local database during development — MCP clients retry aggressively and a slow production endpoint makes debugging miserable. In production, keep write-capable tools behind a feature flag or a separate token scope until you've watched the read-only traffic for a while.

Gotchas and Tips

• Prompts are a new surface area. 1.2.0 introduces prompt loading with no prior assessment to compare against; verify how the resolver is registered (config entry vs. container binding) and confirm it's actually being hit. A silently unregistered resolver just means clients see tools but no prompts, which is easy to misread as a client bug.
• Schema size is your main failure mode. Every exposed field and resource costs tokens and adds choice paralysis. If the model starts hallucinating field names, your tool list is too big — cut resources before you tweak prompt wording.
• Auth failures look like tool failures. Most MCP clients surface a 401/419 as "tool returned an error", not "you're unauthenticated". When something mysteriously stops working, hit the endpoint with curl first.
• CSRF and session middleware bite on the HTTP transport. If you're not using token auth, exempt the MCP route from VerifyCsrfToken deliberately rather than debugging 419s.
• Pagination is invisible to the model. Tools that return "all records" will silently truncate or time out on large tables. Cap result counts in the tool implementation and tell the model in the tool description that results are capped.
• Debug with mcp-inspector rather than through your chat client — it shows the raw tool schemas and response payloads, which is where the actual problems are.
• Pin the version. nova-mcp tracks Nova internals; a Nova upgrade plus an unpinned MCP package is a compound failure you don't want to bisect. Commit the lockfile.
• Extension point: the tool resolver and (now) prompt resolver are the two places to hook in. If you need behaviour the package doesn't offer, subclass the resolver and rebind it in a service provider rather than forking.