Filament MCP

Expose your Filament resources to AI agents over the Model Context Protocol, with per-record create, read, and update tools generated straight from your existing resource forms. Delete tools are available as an explicit per-resource opt-in.

Point Claude Code, Cursor, or any MCP client at your app and let it manage your content the same way a human would in the admin panel, gated by a token and an authorization callback you control.

Why

This package lets an AI agent do everything a human could already do in the Filament dashboard. Where Filament's own AI tooling helps you write Filament code, this does the opposite: it lets an agent operate a running panel. Unlike the read/bulk-action oriented alternatives, it generates real per-record CRUD tools on the official laravel/mcp server, enforces your policies, and is configured almost entirely from a single config file.

• Generated, not hand-written. Each resource's form is introspected, so a new field shows up as a tool argument automatically.
• Safe by default. Access is forbidden until you explicitly grant it in the config.
• Text fields only. Only text-like fields are exposed (see Limitations).
• Audited. Every tool call is recorded and attributed to the token that made it. Review a token's call history on its own activity page in the panel.

Requirements

• PHP 8.2+
• Laravel 12 or 13
• Filament 5

Installation

composer require mattiasgeniar/filament-mcp
php artisan migrate

The config file is published automatically via the install command, or manually:

php artisan filament-mcp:install
# or
php artisan vendor:publish --tag=filament-mcp-config

Configuration

Everything lives in config/filament-mcp.php. The two things you must set are who can access the server and which resources to expose.

1. Who has access

Access is forbidden until you explicitly grant it in the config; nobody can connect until you define who is allowed. Pick one:

A useFilamentMcp gate (recommended, cache-safe):

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate;

Gate::define('useFilamentMcp', fn ($user) => $user->is_admin);

Or a callback (handy when the rule does not belong in a gate):

use Mattiasgeniar\FilamentMcp\FilamentMcp;

FilamentMcp::authorizeUsing(fn ($user) => $user->is_admin);

2. Which resources to expose

// config/filament-mcp.php
use App\Filament\Resources\PageResource;
use App\Filament\Resources\PostResource;
use App\Mcp\PreparePageData;

// ...

'resources' => [
    // Shorthand: enables list/get/create/update when matching Filament pages exist
    PostResource::class,

    // Expanded: scope abilities, opt in to delete, and attach an optional data preparer
    PageResource::class => [
        'read' => true,
        'create' => true,
        'update' => true,
        'delete' => false,
        'prepare' => PreparePageData::class,
    ],
],

prepare points at a class implementing PreparesRecordData. Use it to mirror logic that normally lives in your Filament page (for example slug generation):

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use Mattiasgeniar\FilamentMcp\Contracts\PreparesRecordData;

class PreparePageData implements PreparesRecordData
{
    public function __invoke(array $data, ?Model $record): array
    {
        $data['slug'] ??= Str::slug($data['title']);

        return $data;
    }
}

Custom actions

Expose a custom per-record action as its own tool (the guardrailed way to mirror a Filament action or bulk action). Add an actions map and point each entry at a class extending ResourceAction:

\App\Filament\Resources\PostResource::class => [
    'actions' => [
        'publish' => \App\Mcp\PublishPost::class, // becomes the publish_post tool
    ],
],

use Illuminate\Database\Eloquent\Model;
use Mattiasgeniar\FilamentMcp\Actions\ResourceAction;

class PublishPost extends ResourceAction
{
    public function description(): string
    {
        return 'Publish the post.';
    }

    public function handle(Model $record, array $arguments): mixed
    {
        $record->update(['published' => true]);

        return ['published' => true];
    }
}

The action is authorized before it runs: the acting user must pass the resource policy ability returned by ability() (defaults to update) against the target record, exactly like the built-in write tools. Override ability() to map onto a dedicated policy method.

Arguments are an allowlist: only keys you declare in rules() are validated and forwarded to handle(), so an agent cannot smuggle undeclared attributes into the action. Mirror whatever schema() advertises:

public function schema(JsonSchema $schema): array
{
    return ['reason' => $schema->string()->description('Why it was published.')];
}

public function rules(): array
{
    return ['reason' => ['required', 'string', 'max:255']];
}

Other options

Audit retention

Every tool call is stored in filament_mcp_tool_calls. The package schedules Laravel's model:prune daily to delete records older than audit.retention_days (one year by default). Set FILAMENT_MCP_AUDIT_RETENTION_DAYS=0 to keep the log forever and turn pruning off. Pruning only happens if your app's scheduler is running (schedule:run via cron, or schedule:work in development).

Issuing a token

Tokens are bound to the issuing Filament user model, hashed before storage, and shown only once. Generate one from the CLI:

php artisan filament-mcp:token user@example.com --name="My laptop"

The command refuses to issue a token to a user who is not authorized (override with --force).

In the panel

Users can manage their own tokens from a Filament page instead of the CLI. Register the plugin on your panel:

use Mattiasgeniar\FilamentMcp\Filament\FilamentMcpPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(FilamentMcpPlugin::make());
}

This adds an MCP → Tokens page where each user generates and revokes their own personal tokens (the plaintext is shown once, with a copy button). The page is only visible to users your authorization gate/callback allows, the same rule that guards the server. Customise the navigation, or turn the page off entirely, under the ui config key.

If your panel uses a custom theme, do the one-time step in Using a custom Filament theme so the page is styled.

Using a custom Filament theme

The token page is built from Blade views that ship in this package. Filament compiles a panel's CSS with Tailwind, which only generates the utility classes it finds in the sources you tell it to scan. A custom theme does not scan vendor/, so this package's classes are purged and the page renders unstyled (text and the token field collapse onto one cramped row instead of stacking).

Register the package's views as a Tailwind source in your theme's CSS, then rebuild your assets:

/* resources/css/filament/<your-panel>/theme.css */
@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament/**/*';
@source '../../../../vendor/mattiasgeniar/filament-mcp/resources/views/**/*'; /* add this */

npm run build   # or: vite build

Path depth: the @source is relative to the theme CSS file. From the default resources/css/filament/<panel>/theme.css location that is four levels up (../../../../) to reach the project root, matching the Filament import above.

You only need this with a custom theme. The default Filament theme already compiles every class the package uses, so it works with no extra setup.

Connecting an MCP client

The server speaks the streamable HTTP transport. Point your client at the URL and pass the token as a bearer header. For Claude Code (.mcp.json):

{
  "mcpServers": {
    "my-app": {
      "type": "http",
      "url": "https://your-app.test/filament-mcp",
      "headers": { "Authorization": "Bearer fmcp_..." }
    }
  }
}

Or add it with the Claude Code CLI:

claude mcp add --transport http my-app https://your-app.test/filament-mcp \
  --header "Authorization: Bearer fmcp_..."

Remove it again with:

claude mcp remove my-app

The token page renders this same ready-to-paste config for Claude Code, Cursor, VS Code, and Codex under a Connect a client section, with the endpoint URL already filled in. Hide it with ui.show_setup_guide => false.

If the configured/current Filament panel uses Filament tenancy, include the tenant route key in the X-Filament-Mcp-Tenant header (or the configured tenant_header). The token user must implement Filament's tenant contract and pass canAccessTenant() for that tenant before any tools run.

Each exposed resource can produce list_*, get_*, create_*, update_*, and custom action tools named from the model (e.g. create_post). Built-in operations are only generated when the corresponding Filament resource page exists: list_* requires an index or manage page, get_* requires a view, index, or manage page (so a view-only resource is fetchable by id without exposing a full listing), create requires a create or manage page, and update requires an edit or manage page. delete_* tools are never generated by shorthand config; set 'delete' => true for a resource that should expose deletes, and policy checks still run per record.

The page inference is the default, not a hard gate: an explicit boolean for an operation in the resource config overrides it. Set 'list' => true to expose list_* on a view-only resource that has no index page (handy for read-only, high-volume models like runs), or 'list' => false to hide it where an index page exists. Policies, query scoping, and attribute visibility still apply.

This override is per operation and wins over the broader defaults too. An explicit 'create' => true or 'update' => true re-enables that tool even when 'write' => false is set, and 'delete' => true force-exposes delete_* on a resource with no deletion page. The override only decides whether the tool is generated; every call still runs the model's Filament policy per record, so a force-exposed destructive tool is not an authorization bypass.

A single describe_resources tool lets an agent discover what is exposed (resources, operations, actions, and fields) in one call.

Reads vs writes. Writes (create/update) are driven by the resource's form, so the agent can only set fields the form allows. Reads (list/get) return the union of the resource's infolist (what Filament shows on the view page) and its writable form fields, so the agent can always read back what it can write and still see view-only entries. A resource with only a form, only an infolist, or both is fully readable either way. The model's $hidden and $visible settings are enforced before tool schemas are built, so hidden attributes are excluded from discovery, writes, reads, search, filters, and sort options even if they appear in the form, infolist, or read_fields.

When a resource builds its view schema on the page (a ViewRecord) rather than the resource, introspection finds nothing to read. List the readable attributes explicitly with read_fields:

\App\Filament\Resources\RunResource::class => [
    'write' => false,
    'list' => true, // force-expose list_runs even though the resource is view-only
    'read_fields' => ['check_id', 'result', 'started_at', 'ended_at'],
],

Security model

1. Token — every request needs a valid, non-revoked bearer token.
2. Authorization — the resolved user must pass your gate/callback; access is denied until you grant it.
3. Filament resource surface — by default tools are generated only for operations that have matching resource pages, and delete is an explicit opt-in. An explicit boolean per operation in the resource config overrides this default.
4. Model attribute visibility — fields hidden by the Eloquent model are not exposed in schemas, list controls, or responses.
5. Policies — each tool call also respects the model's Filament policy when one exists.
6. Query scoping — records are read and written through the resource's getEloquentQuery(), so your tenant scopes and soft-delete filters apply.
7. Audit — every call is logged to filament_mcp_tool_calls.

Revoke a token by setting revoked_at on its filament_mcp_tokens row.

Limitations

This is v1 and intentionally scoped:

• Text-like fields only for writes. Text, textarea, markdown/rich editors, selects, toggles/checkboxes, numeric inputs (mapped to integer/number) and date pickers are mapped. File uploads, custom components, and fields the form would not persist (disabled(), dehydrated(false)) are skipped, so the writable surface matches what a real save writes. Reads union the infolist and these form fields (see "Reads vs writes" above).
• Closure-based form validation is not enforced at the MCP layer; database constraints and model events remain the backstop.
• Page-level logic is honored only through a prepare class.
• Token management is available both from the CLI and, when the plugin is registered, as a self-service Filament page per user.

Testing

composer test

Credits

• Mattias Geniar

License

The MIT License (MIT). See LICENSE.md.