README

Staff tooling over MCP for Laravel apps, as a package: the ability catalogue, per-person tokens, access and audit middleware, preview/confirm writes, ground rules, a me resource with per-user assistant memory, saved playbooks, gap reports, usage learning, and a short optional onboarding. Every app that exposes tools to Claude, Codex or another assistant needs the same foundation; this is it, once.

Requires PHP 8.3+, Laravel 12 or 13, laravel/mcp 0.9, Sanctum 4 and spatie/laravel-activitylog 4.9 or 5. Postgres first; other databases work for everything but the JSONB memory column.

What you get

• One catalogue of token abilities ('shop:orders:read' => ['Search orders', 'orders', 'shop']) that the tools, the token command, the tokens page and the tests all read. A token never out-ranks its owner: the permission behind each ability is re-checked on every call.
• Guarded servers. mcp-kit.servers registers each server with auth:sanctum, a per-token throttle, EnsureMcpAccess (blocked owners, inactive service clients, browser sessions, tokens without an ability for this server) and AuditMcpCall. An Mcp::web route that bypasses the kit makes the app refuse to boot.
• One write shape. previewOrExecute() previews without confirm=true and executes with it. Every confirmed write and every tool call becomes an activity_log row in the mcp log, in the person's name, with the sanitised arguments and a call_id shared by the domain rows written during the call.
• {scheme}://me tells the assistant who it is talking to: role, team, what this token may do, how the person usually works, what was remembered. A hint, not a mode.
• remember_about_me saves what the person confirms, in a JSON column on users. getting_started asks only for what the app does not already know, at most three questions, and is offered once.
• What the tools are used for. working_on records why a piece of work was started and whether it succeeded, and stamps every call in between — so {scheme}://usage can show what people actually come here to do and where it falls short. Off by default; me tells the person it is on.
• Gap reports. report_gap files what someone needed and the app could not do — deduplicated, so the same gap gathers weight rather than duplicating, and routed by your own listener on GapReported. {scheme}://gaps lists what is open.
• Playbooks. save_playbook keeps a way of working the person wants back, and every one they saved is offered as an MCP prompt — a slash command in Claude Code. Scope one to certain servers or abilities; privileged staff may share one with everybody. {scheme}://playbooks lists them.
• Hints when an assistant hits a wall. neighbours says which sibling connection owns what this app does not, in every server's instructions and in the gap-report preview; hints.instead_of names the one-call tool when the same tool is called over and over. See Where the road continues.
• Commands: mcp:install, mcp:token, mcp:client-token, mcp:docs, mcp:inventory, mcp:audit-tokens, mcp-kit:prune.
• Tests for free. Guards::all() gives an app the ability, schema, access, inventory, docs, preset, token-command, ground-rules and me checks in one line.

Install

composer require heihallo/mcp-kit
php artisan mcp:install
php artisan migrate

mcp:install publishes config/mcp-kit.php, writes a server class under app/Mcp/Servers, a ground-rules intro view, tests/Feature/Mcp/KitGuardsTest.php with its inventory snapshot, and the docs page. It is safe to run again. Add --scan to have it read the abilities your existing tools already check and add catalogue entries for them.

Then, in config/mcp-kit.php:

'scheme' => 'shop',

'servers' => [
    'shop' => [
        'class' => App\Mcp\Servers\ShopServer::class,
        'path' => '/mcp/shop',
        'label' => 'Shop',
        'wildcard' => 'shop:*',
        'client_name' => 'shop',
        'requires_staff' => true,
    ],
],

'catalogue' => [
    'abilities' => [
        'shop:orders:read' => ['Search and view orders', 'orders', 'shop'],
        'shop:orders:write' => ['Change order status, refund', 'orders', 'shop'],
        'shop:customers:read' => ['Search customers', 'customers', 'shop'],
    ],
    'explicit_only' => [],
    'service_client_writes' => [],
],

'permission_rules' => [
    'staff_permission' => 'access admin',
    'privileged_roles' => ['Owner', 'Dev'],
],

A tool:

use HeiHallo\McpKit\Tools\StaffTool;

#[IsReadOnly]
class SearchOrdersTool extends StaffTool
{
    protected string $name = 'search_orders';
    protected string $description = 'Search orders by number, customer or status.';
    protected array $inputSchema = ['type' => 'object', 'properties' => ['query' => ['type' => 'string']]];

    public function handle(Request $request): Response
    {
        if ($denied = $this->requireAbility($request, 'shop:orders:read')) {
            return $denied;
        }

        return Response::json(['orders' => Order::search($request->get('query'))->map(
            fn (Order $order) => $this->withAdminUrl(['number' => $order->number, 'status' => $order->status], $order),
        )]);
    }
}

A write:

return $this->previewOrExecute(
    $request,
    ['order' => $order->number, 'from' => $order->status, 'to' => $status],
    fn () => ['order' => $order->refresh()->only('number', 'status')],
    'Change order status',
    ['subject' => $order],
);

Mint a token and connect:

php artisan mcp:token kari@example.com

It prints the token and one claude mcp add … line per server the token reaches.

Overriding behaviour

Every replaceable piece is a contract bound from a config key. Point the key at your own class, or re-bind the contract in your provider. Never edit a package file.

Views: php artisan vendor:publish --tag=mcp-kit-views and edit what you need under resources/views/vendor/mcp-kit. A single partial (the ground-rules intro, the tokens-page examples) can be overridden on its own.

Events at every hook point: TokenMinted, TokenRevoked, AccessDenied, AbilityDenied, ToolCallRecorded, WritePreviewed, WriteConfirmed, MemoryUpdated, OnboardingOffered, OnboardingCompleted, OnboardingDeclined.

Activity log

The kit standardises on spatie/laravel-activitylog and adds three columns to its table: source (the product), channel (web, mcp, api, cli, chat, system) and token_name. They are filled on every row as it is created, only where still null, whatever model the app uses. Tool calls land in the mcp log: event is read, previewed, executed, denied or failed; description is the confirmed action or the tool name; properties carry tool, server, arguments, result, duration, call_id, client. mcp-kit:prune removes rows older than activity.retain_days; schedule it daily.

Optional UI

With Livewire 4 and Flux installed, set mcp-kit.ui.enabled and ui.tokens_page.enabled (or run mcp:install --with-tokens-page). The page at settings/tokens mints tokens with a preset filtered by the person's own permissions, lists and revokes them, shows the connect snippets for Claude Code, Claude Desktop, Codex and cURL, and ends with what the assistant remembers about the person. Each client tab also says where to get the client itself — the download link, the one line that installs it on each platform, the command that proves it is there, and the vendor's own instructions — from Tokens\ClientSetup, so every app on the kit tells staff the same thing. The people minting these tokens were told an assistant could read the CRM; they were not told to install anything, and claude mcp add … is not a first instruction. The table and tabs are Flux Pro components. Add the package views to Tailwind: @source '../../vendor/heihallo/mcp-kit/resources/views';.

ui.usage_page.enabled adds a second page at settings/mcp-usage: what the tools were used for and what people needed and could not get — the browser twin of {scheme}://usage and {scheme}://gaps. It refuses anybody who is not privileged, because it is a record of colleagues' work. A gap is decided from here (planned, built, or turned down) with a line saying why; everybody who reported it reads that line the next time they read {scheme}://me.

List tools

PagesResults (already on StaffTool) gives a list tool offset, direction and a per-tool sort, and puts total and has_more on every reply. Merge PAGING_PROPERTIES into the tool's schema, declare its own sort enum, and call applyPaging($query, $request, [...]) before get(). Without it a capped list is indistinguishable from a complete one, and nothing past the cap can be reached at all.

File uploads

MCP carries JSON, not bytes. With uploads.enabled, the kit registers POST /mcp/uploads behind the same token and access gate as the servers: multipart field file in, handle (up_…) out. A tool takes the handle through AcceptsUploads — merge UPLOAD_PROPERTY into its schema, resolve with stagedUpload(), copy from stagedPath() into the app's real home, record it with uploadConsumed(). Staged files belong to the person (not the token — tokens rotate), are listable with the shared list_uploads tool, and expire after uploads.ttl_days (default 3, MCP_UPLOAD_TTL_DAYS): a loading dock, not a warehouse. mcp-kit:prune sweeps the dock.

An assistant behind a connector (Claude, ChatGPT, Codex with the token in its config) talks MCP through a token it never sees, so it cannot send the bearer header. The shared request_upload tool gives it a signed link to POST /mcp/uploads/link instead, bound to the token that asked and valid for uploads.link_minutes (default 30, MCP_UPLOAD_LINK_MINUTES). Behind the link everything is the same: the access gate, the limits, the handle. Revoking the token kills its links.

Where the road continues

An assistant that cannot do something here has no way of knowing whether the job is impossible or simply somebody else's. It gives up, works around it, or spends two hundred calls doing by hand what one tool does in one call. Two pieces of config fix that, and both are the app's own.

neighbours names the sibling connections of the same product family:

'neighbours' => [
    'crm' => [
        'label' => 'Acme CRM',
        'owns' => 'People and everything around them: customers, signups, invoices',
        'tools' => ['search_contacts', 'list_signups'],
        'match' => ['customer', 'kunde', 'signup', 'signups', 'invoice', 'invoices', 'faktura*'],
        'url' => 'https://crm.example.com/settings/tokens',
        'ask' => 'Anything else worth saying about getting in.',
    ],
],

url is where staff mint their own token for that connection, and every hint ends with it rather than with somebody to wait for. The kit renders the list into every server's instructions as What is not here, matches a refused call's arguments against it — the moment an assistant decides the job is impossible — and matches a gap report against it in the preview — so somebody filing "cannot see a customer's invoices" is told where that lives before anything is filed. Confirming still files it: a wrong guess must never swallow a report.

Matching is whole words at both ends, and nothing is stemmed. A word ending in * matches the compound instead — which is how Norwegian is written, where karakter* is what catches karakterfordelingen.

This is your own organisation and nothing else. The list is read by that organisation's staff and their assistants; one client's app must never mention another's. The kit ships neighbours empty and no default will ever fill it.

hints.instead_of names the shorter road within this app:

'hints' => [
    'instead_of' => [
        'get_thing' => ['use' => 'list_things', 'say' => 'takes a whole list at once', 'after' => 5],
    ],
],

Past after calls to that tool in one stretch of work (default hints.after, repeated every hints.repeat_every), the kit appends a sentence to the tool's own reply. The call is answered as normal — a nudge, never a refusal. Counted per stretch of work when learning is on and per token otherwise, never across people, and turned off wholesale with hints.enabled.

Strict parameters

An argument a tool does not declare is refused, naming the closest real parameter, rather than silently dropped — a dropped argument makes the tool answer a different question and sound sure about it. People only; service clients are exempt because their calls are code you change deliberately. Turn it off with MCP_STRICT_PARAMETERS=false, and list anything that should never count as unknown in always_allowed_parameters (default confirm). A tool that turns a field away on purpose — it belongs to another service, or has a tool of its own — declares protected array $refusedParameters = ['name' => 'name is owned by auth.afpt and cannot be changed here'], and that reason is what the caller reads.

Testing in your app

// tests/Feature/Mcp/KitGuardsTest.php
Guards::all(inventory: __DIR__.'/tool-inventory.json');

// tests/Pest.php
Guards::actors(
    staff: fn () => User::factory()->create(),
    privileged: fn () => User::factory()->owner()->create(),
    blocked: fn () => User::factory()->blocked()->create(),
    serviceClient: fn () => ServiceClient::create(['name' => 'harness', 'slug' => 'harness']),
);

Helpers: Testing\Mcp::token(), ::actingWith(), ::listTools(), ::call(), ::readResource(); expectations toBePreview(), toHaveExecuted(), toDenyAbility().

The tool snapshot

tests/Feature/Mcp/tool-inventory.json is the record of what the app deliberately exposes: each server, the tools on it, and the parameters each tool takes.

{
  "crm": {
    "check_contacts": ["identifiers", "limit"],
    "log_outcomes": ["confirm", "follow_up_days", "outcomes", "status"]
  }
}

The guard reads it in three passes, in the order the damage runs:

• A tool that is gone or renamed fails first: every client already calling it breaks.
• A tool that kept its name and changed what it takes fails next — reconcile_subscriptions gained: scope, settle_missing, confirm. A parameter is not a detail of a tool; it is something the tool can now be asked to do, and its name is all a caller has to go on. One flag of that kind was the whole of a near-miss in one of these apps: a reconciliation that would have cancelled the subscriptions it could not match. A parameter that disappears gets its own message, because the clients sending it break either loudly or quietly.
• A tool that appeared fails last, named, with the question of whether it belongs in the catalogue at all.

Re-pin with php artisan mcp:inventory (--check in CI). A snapshot pinned by name alone — a list of strings per server — keeps working and is compared by name; running the command once is how an app opts in to parameters.

Read-only mode

MCP_READ_ONLY=true hides every tool not annotated #[IsReadOnly] and makes previewOrExecute() refuse confirm=true.

Developing the package

createdb mcp_kit_testbench
composer install
vendor/bin/pest

The suite wipes its database on every run and refuses to start against one not named mcp_kit_testbench*.

License

MIT.