Download the PHP package shaxzodbek-uzb/laravel-model-mcp without Composer

Laravel Model MCP

Expose your Eloquent models to AI agents as MCP tools — without handing them the keys to your database.

laravel-model-mcp turns any Eloquent model into a full set of Model Context Protocol tools (list, view, create, update, delete, search) on top of the official laravel/mcp package — and every single call is checked against your Laravel Policies, scoped to the current tenant, and audited. Safe by default, no boilerplate.

The problem

The official laravel/mcp package is excellent, but it makes you hand-write one tool class per operation, and authorization is a manual if inside each handler:

Multiply that by 6 operations × every model you want to expose. Forget the can() check on one of them, and an agent can now edit anything.

The solution

List the models. Register one server. Done — policy-enforced CRUD for all of them:

That's it. You now have list_posts, get_post, create_post, update_post, delete_post, search_posts, describe_post (and the same for comment) — each one running PostPolicy@viewAny, @view, @create, @update, @delete for the authenticated user before it touches a row.

Why this package

This package builds on laravel/mcp — it does not replace it. Transport, OAuth, and the protocol stay with the official package; this layer adds the opinionated, safe-by-default model exposure on top.

Installation

Requires PHP 8.2+ and Laravel 12.41+ / 13.x (it relies on laravel/mcp's JSON Schema builder). If you haven't set up laravel/mcp yet:

Optionally publish the config:

Quickstart

1. Add a policy for the model you want to expose (standard Laravel — nothing special):

2. Expose the model:

3. Register the server in routes/ai.php behind your auth middleware:

4. See exactly what you exposed:

Point any MCP client (Claude, your agent, php artisan mcp:inspector) at the server and the tools are live — each one acting as the authenticated user.

The security model

This is the whole point, so it's worth being explicit. By default:

1. Nothing is exposed implicitly. Only models in model-mcp.models (or tagged with #[McpModel]) become tools.

2. Every operation enforces the matching policy ability for the authenticated MCP user, before any read or write:

   Operation	Policy ability
   list, search	viewAny
   view	view
   create	create
   update	update
   delete	delete

3. Fail-closed. No policy for the model → every operation is denied. No authenticated user → denied. (Both configurable, both default to safe.)
4. Tenant scope is applied to the query before the policy runs, so even a missing or over-permissive policy can't leak another tenant's rows. If tenancy is enabled and no tenant resolves, the request fails closed.
5. Writes are limited to $fillable; reads honor $hidden; and fields.always_hidden is a hard block on top (e.g. password).

Denials and errors come back as MCP isError results with safe messages — the agent can recover, and your internals never leak. Every call (allowed, denied, errored) is recorded by the audit log.

See SECURITY.md for the full model and how to report issues.

Configuration

The published config/model-mcp.php is fully documented. The essentials:

Read-only or partial exposure

Expose only the operations you want, per model:

Or flip a single global kill-switch so no model can ever be mutated — only list / view / search tools are generated, regardless of per-model settings:

describe — so the agent stops guessing

Without it, the only way for an agent to learn a model's shape is to call list and read whatever comes back. That needs a row to exist, needs the caller to be allowed to see it, and still says nothing about which fields are writable, which are required, or what a date column expects. Each unknown becomes a failed create and a retry.

It is metadata only: it reads the model's schema and this package's config, never a row. So it needs no tenant scope and cannot leak data.

It is still gated on viewAny, and it hides exactly what every other response hides ($hidden, fields.always_hidden). Which models exist and what columns they have is itself information — describe must not become the way to discover a column the model deliberately hides. Switch it off per model like any other operation.

Multi-tenancy

If your app already scopes models with global scopes (a BelongsToTenant trait, #[ScopedBy], stancl/tenancy, spatie/laravel-multitenancy), you need to do nothing — every query runs through Model::query(), so your scopes apply transparently and are never stripped.

Turn on the package's own explicit scoping only when a global scope alone won't filter (e.g. you want a hard where(tenant_column, id) regardless):

The default AuthUserTenantResolver reads the column off the authenticated user ($user->tenant_id). Provide your own by binding Blaze\ModelMcp\Contracts\TenantResolver.

Audit log

Every tool call is recorded with the acting user, the model, the operation, and the outcome (allowed / denied / error). The default LogAuditor writes to your log channel; swap in your own to persist to a table:

Attribute discovery (optional)

Prefer to opt in from the model itself? Enable discovery and tag your models — it's off by default so nothing is ever exposed by accident:

Extending

• Custom tools alongside generated ones — subclass ModelMcpServer and add your hand-written tools to the $tools array; the generated ones are merged in.
• Custom policies — point a model's policy option at any class, or rely on Laravel's normal policy resolution.
• Custom auditor / tenant resolver — implement the contract and bind it.

Requirements

• PHP 8.2+
• Laravel 12.41+ or 13.x
• laravel/mcp ^0.8

Testing

Credits

Built by Blaze. Stands on the shoulders of the laravel/mcp team.

License

The MIT License (MIT). See LICENSE.