Filament Mcp Laravel Package

Getting Started

Install and wire it up

composer require mattiasgeniar/filament-mcp
php artisan vendor:publish --tag="filament-mcp-config"

Check your laravel/mcp version before anything else. As of v0.1, the package tracks Laravel MCP 1.0. If your app is still on laravel/mcp 0.x, Composer will silently resolve you to v0.0.10 and you'll be reading docs for a package version you don't have. Run composer show laravel/mcp mattiasgeniar/filament-mcp and confirm both. The upgrade path is: bump laravel/mcp to ^1.0 first, read the upstream 1.0 upgrade notes, then take filament-mcp v0.1 — the release note is a single line, so assume the behaviour changes come from upstream, not from this package.

Then read the published config/filament-mcp.php first — it is the whole package. You need three things configured before anything works:

1. The token(s) the MCP client will present. The README describes a token-gated server, so treat this as the primary auth boundary and generate a distinct token per agent/environment (~/.claude.json / Cursor config holds it, not your repo).
2. The authorization callback you control. This is where you decide what an agent may do — it is not Filament's panel auth, so don't assume your User model's policies are applied automatically. Verify this deliberately (see Gotchas).
3. Which resources are exposed. Start with a whitelist of one or two, not "all".

Confirm the MCP server is actually registered — the package builds on the official laravel/mcp server, so php artisan list should show the MCP serve/route command. v0.1 changed the upstream server API, so if the command is missing after the upgrade, you're looking at a registration/API mismatch, not a config typo. Point Claude Code or Cursor at that endpoint with the token and ask the client to list its tools before you ask it to do anything. The tool list is your debugging ground truth.

Where to look next

• The package's own tests/ directory — with a PHPStan badge and a tests badge but only ~13 stars, the test suite is the most reliable specification of behaviour, especially around form introspection and authorization. On v0.1, check that the suite has been updated for the laravel/mcp 1.0 API before trusting green.
• CHANGELOG.md before you pin a version. v0.1's changelog is one line, so treat the upstream laravel/mcp changelog as the real release notes.
• The generated tool schemas themselves (tools/list output) rather than the README, since they are derived from your forms and therefore your reality.

First use case

Pick a low-blast-radius resource — a Post, Product, or Category — and enable read only first. Have the agent list and fetch records and narrate what it sees. Only then add create/update. Leave delete off entirely for the first sprint; it's an explicit per-resource opt-in for a reason.

Implementation Patterns

Roll out in capability tiers. Treat the three capabilities as independent feature flags per resource: list/show → create/update → delete. Most teams will never need delete; the agent can call an update to soft-delete or set a status column instead, which is auditable and reversible.

Your form schema is now a public API contract. Because tools are introspected from the form, every TextInput::make('title')->required()->maxLength(255) becomes a tool argument with those constraints. Two consequences:

• Use helperText() and label() deliberately — they are the prompt the model reads when filling the argument.
• Keep resource forms intentional. A form with a 30-field Repeater and a Builder becomes a 30-argument tool with a monstrous JSON schema, which burns context and confuses the model. Consider a slimmed-down form or a separate resource for agent-facing work.

Let validation do the work. Don't re-implement rules in the agent's prompt. Required fields, maxLength, unique, exists, and Rule objects all surface as tool-schema constraints and server-side validation errors, and a competent MCP client will read the error and retry. Good errors beat good prompting.

Keep the human and agent paths identical. The whole value proposition is that a new field shows up in the agent's tools automatically. Resist the urge to fork a separate "agent form" unless you genuinely need a narrower surface — the moment you fork, you own drift.

Authorize narrowly, in the callback. Pattern this as: token → identity/scope → policy check. Log the decision. If your callback returns a boolean, add logging around it, because a silent false looks identical to a missing tool from the client's perspective.

Use separate tokens per agent and per environment. A staging token in CI, a personal token in your editor, a read-only token for a "reporter" agent. Never reuse the prod-write token locally.

Complement, don't replace, custom tools. Generated CRUD handles the boring 80%. For anything with side effects — "publish and notify subscribers", "import CSV" — write a small explicit tool or a Filament Action and expose that, so the agent can't assemble the wrong sequence of primitive writes. Verify the custom-tool API against laravel/mcp 1.0, since that is where the breaking changes land.

Test the tools like an API. Feature-test the MCP endpoint: assert a tool exists for a resource, assert the schema contains a new field after you add it to the form, assert an unauthorized token gets nothing back. This is cheap insurance for a young package — and it is also your upgrade safety net for exactly this kind of dependency-major bump.

Gotchas and Tips

• The v0.1 bump is a dependency-major bump in disguise. The release note reads "Support Laravel MCP 1.0" with a single commit; the risk surface is upstream. Before upgrading: bump laravel/mcp first, snapshot your tools/list output before the upgrade, and diff it after. Argument names, required-ness, and error shapes are the things most likely to shift without a line in this package's changelog.
• Form fields ≠ safe fields. Introspection follows the form, which may include fields you'd never want an agent writing: is_admin, role_id, published_at, price. Audit each exposed resource with fresh eyes and ->hidden() / ->disabled() anything sensitive — but verify how those map into the generated schema, because a hidden field that's still required() is a trap. Re-verify after any upgrade, since this mapping is introspector logic.
• Which user do policies evaluate as? With token-based auth there's often no auth()->user(), so Gate/policy checks may pass, fail, or throw depending on the implementation. Confirm this on day one with a resource that has a restrictive policy. Do not assume $user->can() guards are doing anything. If laravel/mcp 1.0 reworked how requests are authenticated, this is the first thing to retest.
• Complex field types are the weak spot. FileUpload, RichEditor, Repeater, Builder, KeyValue, and Select::relationship() with thousands of options rarely map cleanly to JSON tool arguments. Probe each one you actually use before enabling that resource; don't let an agent attempt a file upload on a Friday afternoon.
• Dynamic options cause schema churn. A Select whose options() hits the database means the tool schema changes as data changes — or gets frozen at boot. Prefer enums and static option lists for agent-facing fields.
• Side effects fire. Observers, model events, notifications, and queued jobs execute exactly as they would in the panel. An agent creating 40 records can send 40 emails to real customers. Disable notifications outside prod, or gate the resource.
• Agent actions are often unattributed. In the panel you get created_by from auth(). Over MCP there may be no user. Add explicit attribution (a source column, an audit log, or a wrapper in your authorization callback) if "who did this?" matters — and it will, the first time something looks wrong.
• Context cost. Each exposed resource contributes tool definitions to every request. Ten resources with fat forms can consume a serious fraction of the model's context before you've asked a question. Expose resources per-agent if your client supports it (many allow per-server/per-project tool filtering).
• Debugging order: client logs → tools/list output → your authorization callback's logs → the package's tests/. If a tool is missing, it's almost always the resource whitelist or the callback returning false, not the form introspector. On a fresh major bump, add "is the MCP server command even registered?" to the top of that list.
• Pin the version and read the changelog. Small package, recent, one primary maintainer (now with a contribution from Freek Van der Herten, which is a good signal — but it does not change the risk profile). MIT, tests, PHPStan. It means you are partly the QA. Lock a version, run its suite in your CI, and wrap what you depend on in your own tests so an upgrade can't silently change a tool's arguments. There are now two supported lines — v0.1 on laravel/mcp ^1.0 and v0.0.10 on 0.x — so state explicitly in your composer.json which one you're on and why.
• Extension points to know: the config file is the main seam (resource registration, tokens, callback). Beyond that, check whether the package allows supplying custom tool classes or overriding the generator — that's where you go when a resource needs a hand-written tool instead of a generated one. Those hooks are the most likely casualty of an upstream 1.0 API change; re-read the package source after upgrading rather than assuming they still exist.
• Never point a write-capable token at production until you've watched it operate against a seeded staging copy for a full week — and restart that clock after a major dependency bump. The failure mode here isn't a crash, it's an agent confidently doing 200 plausible-but-wrong updates.