Nova Mcp Laravel Package

Getting Started

Start by installing and wiring the MCP server, then verify read access before enabling writes.

• composer require mdrbx/nova-mcp and follow the README’s server registration and token setup. Tokens are ability-scoped; use nova:read for read-only clients and nova:write only where mutations are intended.
• Read the README and architecture notes first. They are the source of truth for tool arguments, native response shapes, configuration keys, and the consent screen. The consent screen and screenshot reflect the expanded write scope in v0.2.0.
• Configure via environment: NOVA_MCP_READ_ONLY=true disables all MCP resource mutations, including for previously issued write tokens. Writes are enabled by default, so set read-only explicitly in staging and production unless the use case requires mutation.
• Customize client-facing guidance with NOVA_MCP_GUARDRAILS. Treat this as instruction text for MCP clients, not as an authorization layer.
• After changing any MCP environment setting, rebuild the config cache (php artisan config:cache or your deployment equivalent). No new migrations or frontend build are required in v0.2.0.
• First use case: connect an MCP client, list Nova resources, fetch a record, then exercise a safe read-only action or relationship read. Once that works, enable a single write token and test one scoped operation such as attaching a BelongsToMany record in a non-production environment.

Implementation Patterns

Use Nova’s existing authorization and policy layer as the boundary, and keep MCP tokens narrowly scoped per client or workflow.

• Separate read and write tokens. Issue nova:read tokens to analysis or support agents and nova:write tokens only to automation that must mutate records. Combine this with NOVA_MCP_READ_ONLY=true for environments where no writes should occur at all.
• Relationship writes through native Nova behavior. BelongsToMany and MorphToMany fields support attach and detach, including pivot validation. Create related HasMany and MorphMany children through the same Nova controllers and policies used by the UI. Restore and force-delete operations follow Nova’s documented behavior; replication forms can be discovered and used to prefill create operations.
• Synchronous actions only. Expose actions that complete within the request. Nova visibility, field validation, canRun, and policy checks are honored. Queued, standalone, and pivot actions remain excluded, so wrap long-running work in a synchronous action only when it is genuinely fast, or keep it outside MCP.
• Guardrails are UX, not security. Use NOVA_MCP_GUARDRAILS to tell clients what the server expects, but rely on token abilities, NOVA_MCP_READ_ONLY, Nova policies, and canRun for enforcement.
• Test against the MCP surface, not only HTTP. Add feature tests that exercise tool calls with a read token and a write token, including a denied write under read-only mode and a policy-denied action. Keep PHPStan/Rector/Pint in CI if you extend the package.
• Deployment workflow. Treat MCP configuration like any other Laravel config: change env vars, clear/rebuild config cache, restart workers, and verify the effective token abilities and read-only flag from the server side.

Gotchas and Tips

• Writes are enabled by default. v0.2.0 does not make the server read-only unless you set NOVA_MCP_READ_ONLY=true. Existing write tokens are also blocked when read-only is enabled, so flipping the flag is a real kill switch.
• Config cache surprises. Changing NOVA_MCP_READ_ONLY or NOVA_MCP_GUARDRAILS without rebuilding Laravel’s config cache will leave the old behavior in place.
• Undefined policy methods fall back to Nova defaults. If your policies are incomplete, MCP operations may be allowed where you expected a denial. Explicitly define viewAny, view, create, update, delete, restore, forceDelete, and action-related methods for resources exposed over MCP.
• Pivot validation errors are easy to misread. Attach/detach failures can come from pivot rules, missing pivot fields, or policy checks. Log the Nova validation response and the token ability used before assuming the MCP layer rejected the call.
• Morph relationships need a stable morph map. If your app enforces a morph map, verify MorphToMany and MorphMany operations use the aliases Nova expects; otherwise create/attach calls can fail validation or resolve the wrong model.
• Queued actions are intentionally excluded. Do not expose a queued action and expect MCP to wait for it. If the workflow needs asynchronous behavior, trigger a synchronous action that dispatches a job and returns promptly, or keep the job behind a separate endpoint.
• Guardrail text is not enforcement. A client can ignore NOVA_MCP_GUARDRAILS. Always verify authorization server-side and avoid putting secrets or destructive instructions in guardrail text.
• Debugging checklist: confirm the token has the required ability, confirm NOVA_MCP_READ_ONLY is false for writes, confirm the Nova policy allows the operation for the token’s user, confirm the action is synchronous and visible, and inspect the native Nova response before changing MCP configuration.
• Version matrix: v0.2.0 targets PHP 8.3–8.5 and Laravel 12–13. Pin compatible versions in composer and run the package’s validation stack locally if you fork or extend it.