MCP Server

Filament Studio ships a built-in Model Context Protocol (MCP) server. Connect any MCP-compatible AI assistant (Claude, Cursor, Windsurf, etc.) and let it manage your data model — create collections, define fields, query records, build dashboards — all through natural language.

Enabling

MCP is disabled by default. Enable it in your environment:

STUDIO_MCP_ENABLED=true

Or publish and edit the config:

php artisan vendor:publish --tag="filament-studio-config"

// config/filament-studio.php
'mcp' => [
    'enabled' => env('STUDIO_MCP_ENABLED', false),

    'http' => [
        'enabled' => env('STUDIO_MCP_HTTP_ENABLED', true),
        'prefix'  => env('STUDIO_MCP_HTTP_PREFIX', 'ai/studio'),
    ],

    'stdio' => [
        'enabled' => env('STUDIO_MCP_STDIO_ENABLED', true),
        'handle'  => env('STUDIO_MCP_STDIO_HANDLE', 'studio'),
    ],
],

Authentication

The MCP server authenticates every request with a Studio API Key. Create one under Studio → API Settings in your admin panel — enable Wildcard Access to grant the key permission over all collections.

For stdio transport, pass the key as an environment variable:

STUDIO_API_KEY=your-plaintext-api-key

For HTTP transport, pass it as a header on each request:

Authorization: Bearer your-plaintext-api-key

The key is stored as a SHA-256 hash. The plaintext is only shown once at creation time.

Key Scoping

API keys can be global (tenant_id = null, wildcard access) or tenant-scoped (tenant_id set to a specific tenant). The MCP server inherits this scope — all tool calls from a tenant-scoped key automatically filter to that tenant.

Connecting to Claude Code

Add an mcp.json file to your project's .claude/ directory:

{
  "mcpServers": {
    "filament-studio": {
      "type": "stdio",
      "command": "php",
      "args": ["artisan", "mcp:start", "studio"],
      "env": {
        "STUDIO_API_KEY": "your-plaintext-api-key",
        "STUDIO_MCP_ENABLED": "true"
      }
    }
  }
}

If your app runs inside Docker:

{
  "mcpServers": {
    "filament-studio": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "exec", "-i",
        "-w", "/var/www/html/your-app",
        "-e", "STUDIO_API_KEY=your-plaintext-api-key",
        "-e", "STUDIO_MCP_ENABLED=true",
        "your-php-container",
        "php", "artisan", "mcp:start", "studio"
      ]
    }
  }
}

Restart Claude Code after saving the file. The filament-studio server will appear in the MCP panel.

HTTP Transport

When HTTP is enabled, the server mounts at the configured prefix (default ai/studio). Use this for remote connections or Streamable HTTP clients:

POST https://your-app.com/ai/studio
Authorization: Bearer your-plaintext-api-key
Content-Type: application/json

The HTTP endpoint is protected by the studio-mcp rate limiter (default 120 req/min) in addition to API key authentication.

Resources

Resources are read-only reference documents the AI should read before using tools.

Recommended workflow: Read studio://info, studio://field-types, studio://panel-types, and studio://operators before running any tools. This gives the AI the full catalog of what's available.

Tools

Collections

Fields

Records

Dashboards

Panels

Saved Filters

API Keys

Confirm Tokens (Two-Step Deletes)

Destructive operations — deleting collections, fields, and dashboards — require a two-step flow to prevent accidental data loss:

1. Call the preview_delete tool. It returns an impact summary and a short-lived confirm_token.
2. Pass the confirm_token to the delete tool within the TTL window (default 5 minutes).

studio_preview_delete_collection → { impact: {...}, confirm_token: "abc123", expires_at: "..." }
studio_delete_collection         ← { confirm_token: "abc123" }

The token is scoped to the specific operation and target — it cannot be reused for a different resource. Configure the TTL:

STUDIO_MCP_CONFIRM_TOKEN_TTL=300

Querying Records

studio_query_records accepts the same FilterGroup tree used by the REST API and the Filament filter builder:

{
  "collection_slug": "posts",
  "tenant_id": "t1",
  "filter": {
    "operator": "AND",
    "rules": [
      { "field": "status", "operator": "eq", "value": "published" },
      { "field": "views",  "operator": "gte", "value": 100 }
    ]
  },
  "sort": [{ "field": "created_at", "direction": "desc" }],
  "per_page": 25,
  "page": 1
}

Available operators are documented in studio://operators. Nesting depth is limited by STUDIO_MCP_QUERY_MAX_FILTER_DEPTH (default 5).

Rate Limiting

HTTP requests are rate-limited per API key. Configure the limit:

STUDIO_MCP_HTTP_RATE_LIMIT=120

Stdio transport has no rate limiting — it runs as a local process under your control.

Limits

Logging

MCP requests and errors are logged to the configured channel:

STUDIO_MCP_LOG_CHANNEL=stack
STUDIO_MCP_LOG_REQUESTS=true
STUDIO_MCP_LOG_ERRORS=true

Set STUDIO_MCP_LOG_REQUESTS=false in production to reduce log volume.