DEV Community: Tom Shaw

Wiring components to server-rendered pages with domwire

Tom Shaw — Thu, 11 Jun 2026 17:21:38 +0000

domwire is a DOM-driven, on-demand component loader for plain JavaScript and TypeScript applications. It initializes ES6 classes from data-component attributes in your markup, manages their lifecycle, and lazy-loads their code only when the matching element actually exists on the page. It has zero runtime dependencies and weighs about 2 KB minified.

This tutorial covers why the library exists, the problem it solves, how the approach works, and how to use every part of the API.

1. The problem

Most web applications are not single-page apps. Server-rendered sites — Rails, Laravel, Django, WordPress, static sites — still need JavaScript behavior: a date picker here, a carousel there, an autocomplete on one form out of fifty pages. The question every one of these codebases has to answer is: how does a piece of JavaScript find out whether the page it's running on needs it?

The answer you find in most codebases, including ones written by experienced developers, looks like this:

// app.js — runs on every page
import UserCard from "./components/UserCard.js";
import Carousel from "./components/Carousel.js";
import DatePicker from "./components/DatePicker.js";
import Autocomplete from "./components/Autocomplete.js";
// ...30 more imports

document.addEventListener("DOMContentLoaded", () => {
    const userCard = document.querySelector(".user-card");
    if (userCard) new UserCard(userCard);

    const carousel = document.querySelector(".carousel");
    if (carousel) new Carousel(carousel);

    document.querySelectorAll(".date-picker").forEach((el) => {
        new DatePicker(el);
    });

    const search = document.querySelector("#search");
    if (search) new Autocomplete(search, { minChars: 3 });

    // ...30 more of these
});

Sometimes it's dressed up as an array of { selector, klass } pairs with a loop over it, but it's the same pattern. Every component in the entire application interrogates every page: "am I needed here?"

Why this is fundamentally awkward

The direction of the question is inverted. The server already knows exactly which components a page needs — it rendered the markup. But that knowledge is thrown away, and the client re-derives it by checking every selector the application has ever defined against the current document. The page should declare what it needs; instead, every script asks.

Every page pays for every component. All 34 imports above are in the bundle whether the current page uses zero of them or all of them. The blog index downloads, parses, and executes the checkout form's validation logic. Code splitting is technically possible, but the manual pattern gives you no natural seam to split along.

The wiring file becomes a bottleneck. Every new component means editing the same central file: add an import, add a selector check. The file grows monotonically, merge conflicts concentrate there, and nothing ever gets removed because nobody is sure which pages still use which selector.

Configuration gets smuggled through ad-hoc channels. One component reads data-min-chars, another reads a global, another parses a class name like carousel--speed-3. There is no convention because the pattern doesn't provide one.

Dynamically inserted markup silently does nothing. The selector checks run once at DOMContentLoaded. Content that arrives later — an htmx swap, a fetched partial, an infinite-scroll page — contains markup that looks right but is inert, because the check already ran. The usual fixes (re-running the whole init function, framework-specific re-init events) are fragile and re-initialize things that were already alive.

Teardown doesn't exist. When a node holding a component is removed, its event listeners on window or document, its timers, and its observers keep running. The manual pattern has no place where destruction could even happen.

None of these are exotic edge cases. They are the default failure modes of the pattern, and they show up in almost every non-framework codebase of meaningful size.

2. The idea behind domwire

domwire inverts the question. Instead of every component asking the page "do you need me?", the page states what it needs:

<div data-component="user-card" data-options='{"id": 42}'></div>

and a single manager walks the DOM once, looks up each declared name in a registry, loads the matching class, and instantiates it on that element:

import { ComponentManager } from "domwire";

const manager = new ComponentManager({
    registry: {
        UserCard: () => import("./components/UserCard.js"),
        Carousel: () => import("./components/Carousel.js"),
        DatePicker: () => import("./components/DatePicker.js"),
    },
});

await manager.boot();

That's the entire wiring for the whole application. Three things changed structurally:

The markup is the manifest. The server-side template that renders the element also declares its behavior, in the same place. The knowledge the server had is no longer discarded.
The registry holds importers, not classes. () => import(...) is a function that hasn't run yet. A page with no user-card element never downloads UserCard.js. The bundler sees the dynamic import and splits each component into its own chunk automatically.
There is exactly one query. One querySelectorAll("[data-component]") per boot, instead of N selector checks for N components.

3. Getting started

Install

npm install domwire

Write a component

A component is a class extending AbstractComponent. It receives the element it was declared on and the parsed options:

// components/UserCard.js
import { AbstractComponent } from "domwire";

export default class UserCard extends AbstractComponent {
    mounted() {
        this.el.textContent = `User ${this.options.id}`;
    }

    destroy() {
        // remove listeners, cancel timers, etc.
    }
}

this.el is the HTMLElement carrying the data-component attribute. this.options is the object parsed from data-options. The component must be the module's default export — that is what the loader unwraps.

Declare it in markup

<div data-component="user-card" data-options='{"id": 42}'></div>

The attribute value is kebab-case; the registry key is its PascalCase form (user-card → UserCard). This keeps the HTML idiomatic (HTML is case-insensitive, so PascalCase attributes are unreliable) while the registry keys match your class and file names.

Boot

import { ComponentManager } from "domwire";

const manager = new ComponentManager({
    registry: {
        UserCard: () => import("./components/UserCard.js"),
    },
});

await manager.boot();

boot() queries the document for [data-component], and for each match: parses the options, loads the class through the registry, instantiates it, and runs the init lifecycle. All elements initialize concurrently — boot() resolves when every component on the page is mounted.

You can boot a subtree instead of the whole document by passing a root: manager.boot(someContainer).

4. Passing options

Options travel as JSON in data-options:

<div
    data-component="autocomplete"
    data-options='{"minChars": 3, "endpoint": "/api/search", "limit": 10}'
></div>

export default class Autocomplete extends AbstractComponent {
    mounted() {
        const { minChars = 2, endpoint, limit = 5 } = this.options;
        // ...
    }
}

This replaces every ad-hoc configuration channel — per-attribute reads, globals, encoded class names — with one convention. Server templates produce it trivially:

<div data-component="autocomplete"
     data-options="<%= { minChars: 3, endpoint: search_path }.to_json %>"></div>

Invalid JSON does not break the page: domwire logs a warning and the component receives {}.

In TypeScript, options are typed via the generic parameter:

interface AutocompleteOptions {
    minChars?: number;
    endpoint: string;
    limit?: number;
    [key: string]: unknown;
}

export default class Autocomplete extends AbstractComponent<AutocompleteOptions> {
    mounted() {
        this.options.endpoint; // string — typed
    }
}

5. The lifecycle

Each instance runs through six hooks. On initialization:

beforeCreate → created → beforeMount → mounted

and on teardown:

beforeDestroy → destroy

All hooks are optional — implement only the ones you need. In practice, mounted is where setup belongs (listeners, initial render, fetches) and destroy is where cleanup belongs:

export default class Dropdown extends AbstractComponent {
    mounted() {
        this.onDocClick = (e) => {
            if (!this.el.contains(e.target)) this.close();
        };
        document.addEventListener("click", this.onDocClick);
    }

    destroy() {
        document.removeEventListener("click", this.onDocClick);
    }
}

The teardown hooks are what the manual pattern structurally lacks. Because the manager tracks every instance in a Map<HTMLElement, AbstractComponent>, it can tear components down deterministically — either when you call destroyComponent(el) / destroyAll(), or automatically when observed nodes leave the DOM (next section).

6. Dynamic content: `observe()`

Pages that mutate after load — htmx or Turbo swaps, fetched partials, modals injected on demand, infinite scroll — are where the manual pattern breaks down hardest. domwire handles them with a MutationObserver:

await manager.boot();
manager.observe();

From that point:

Any inserted node matching [data-component] (or containing matches in its subtree) is initialized automatically, through the same registry, options parsing, and lifecycle as boot().
Any removed node holding an instance (or containing instances) gets beforeDestroy → destroy and is dropped from the instance map.

This means a server can return a fragment like

<div data-component="chart" data-options='{"series": [3, 5, 8]}'></div>

from any endpoint, a library like htmx can swap it in, and it simply works — no re-init call, no custom events, no coupling between the swapping mechanism and the component system. Call manager.unobserve() to stop watching.

The destroy side is just as important: components removed by a swap release their listeners and timers instead of leaking. The combination — declarative init plus automatic teardown — is what makes long-lived, partially-updating pages safe.

7. Lazy loading in depth

This is the part that changes your bundle profile, so it deserves a closer look.

A registry entry is an importer: a function returning a promise of a module with a default export.

registry: {
    UserCard: () => import("./components/UserCard.js"),
}

Three properties fall out of this shape:

Code splitting is automatic. Bundlers (Vite, webpack, Rollup, esbuild) treat each dynamic import() as a split point. Each component becomes its own chunk without any bundler configuration. Your entry bundle contains domwire (~2 KB) plus the registry — a map of names to thin importer functions.

Loading is demand-driven by the DOM itself. The importer only runs when an element declaring that component exists. The cost model becomes exact: a page pays for precisely the components it renders, nothing more. A heavy chart library behind a chart component costs zero bytes on every page without a chart.

Eager loading remains available where it's the right call. For a tiny component used on every page, skip the network round-trip:

import SiteNav from "./components/SiteNav.js";

registry: {
    SiteNav: () => Promise.resolve({ default: SiteNav }), // eager, in main bundle
    Chart:   () => import("./components/Chart.js"),       // lazy, own chunk
}

The registry is also the single audit point the manual pattern never had: one object that lists every component the application can instantiate. Components missing from it trigger the onMissing callback rather than failing silently.

8. Namespaces

Larger applications can scope registry keys by passing namespace in the options:

<div data-component="card" data-options='{"namespace": "admin"}'></div>

resolves to the registry key admin/Card:

registry: {
    "admin/Card": () => import("./admin/components/Card.js"),
    "Card":       () => import("./components/Card.js"),
}

This lets independent sections of an application (or separately-owned bundles) use the same component names without collision.

9. Error handling

Two callbacks cover the failure paths:

new ComponentManager({
    registry,
    onMissing: (name, el) => {
        // a data-component name with no registry entry
        reportToMonitoring(`unknown component: ${name}`);
    },
    onError: (name, err, el) => {
        // the component constructor threw
        reportToMonitoring(err);
    },
});

The defaults log to the console. A failing component never takes down the boot — every element initializes independently, so one broken widget leaves the rest of the page functional. This isolation is another thing the manual pattern lacks: in a single linear init function, one thrown error aborts everything after it unless every block is individually wrapped in try/catch.

10. Accessing instances and interop

After initialization, the instance is reachable two ways:

manager.instances.get(el); // from the manager's Map
el._component;             // directly from the element

The el._component back-reference makes the system interoperable with anything else that can find a DOM element — event handlers, other scripts, the browser console ($0._component while inspecting), and Alpine.js.

Alpine.js integration

If you use Alpine for light templating alongside domwire components:

import { registerAlpineMagic } from "domwire/alpine";
registerAlpineMagic();

This registers a $component magic that resolves to the nearest [data-component] ancestor's instance:

<div data-component="cart">
    <button x-data @click="$component.addItem(7)">Add</button>
</div>

Alpine handles the inline reactivity; the domwire class holds the real logic and state.

11. Why this approach

It is worth being precise about why this design holds up against the alternatives.

Against the manual selector-check pattern

Every deficiency listed in section 1 maps to a structural property of domwire:

Manual pattern	domwire
Every component checks every page	The page declares its components; one DOM query total
All component code in every bundle	Importers load per-component, per-page, on demand
Central wiring file edited for every component	Markup is the wiring; the registry is a flat declarative map
Ad-hoc configuration channels	One convention: JSON in `data-options`
Dynamic content is inert	`observe()` initializes and destroys automatically
No teardown anywhere	Tracked instances, lifecycle hooks, automatic destroy on removal
One error aborts the init sequence	Per-element isolation with `onError`/`onMissing`

The key conceptual shift is direction: control flows from the document to the code. The document is already the one artifact that accurately describes the page — the server built it. Treating it as the source of truth removes an entire category of synchronization problems, because there is nothing to keep in sync.

Against adopting a framework

React, Vue, or Svelte solve this problem too — but by owning the DOM. For a server-rendered application, that means either rewriting rendering in the framework or maintaining hydration boundaries, build integration, and a client-side rendering model the application didn't need. domwire's scope is deliberately narrow: it connects classes to existing server-rendered elements. It doesn't render, doesn't manage state, doesn't own the DOM. Your components are plain ES6 classes that do ordinary DOM work, and the entire abstraction is small enough to read in one sitting (~230 lines of source).

Against Web Components / custom elements

Custom elements (<user-card>) offer browser-native lifecycle and are a reasonable alternative. The trade-offs that favor data-component attributes:

Behavior attaches to existing semantic elements — a <form>, a <table>, a <nav> — without wrapping them in a new tag or fighting CSS expectations around unknown elements.
Lazy loading must be hand-built around customElements.define (you need a separate lazy-definition mechanism); in domwire it is the default shape of the registry.
Options pass as one typed JSON object rather than string attributes parsed one at a time.
No shadow DOM implications, no constructor restrictions (custom element constructors can't touch attributes or children), no upgrade-timing subtleties.

Custom elements shine for distributable, encapsulated widgets. For wiring application behavior onto server-rendered pages, the attribute-plus-registry model is simpler and more direct.

Against jQuery-style plugins

$(".date-picker").datepicker() is the manual pattern with different syntax — the selector checks, the all-pages bundle, the missing teardown, and the inert dynamic content all carry over unchanged.

The cost

Honest accounting: you take on one attribute convention in your markup, a registry file, and a ~2 KB runtime. Component code itself is unchanged — they are classes that receive an element, which is what you would have written anyway. There is no compiler, no build-step requirement beyond what your bundler already does, and no lock-in: removing domwire means replacing boot() with the manual wiring it eliminated.

12. API reference

`ComponentManager`

new ComponentManager({
    selector?: string;     // default "[data-component]"
    registry?: ComponentRegistry;
    loader?: ComponentLoader;   // supply your own resolution strategy
    onMissing?: (name: string, el: HTMLElement) => void;
    onError?: (name: string, err: unknown, el: HTMLElement) => void;
})

Member	Description
`boot(root?)`	Initialize all matching elements under `root` (default: `document`). Resolves when all are done.
`observe(root?)`	Watch for added/removed matching nodes; init and destroy automatically.
`unobserve()`	Stop watching.
`initializeComponent(el)`	Initialize a single element manually.
`destroyComponent(el)`	Run teardown hooks and forget the instance.
`destroyAll()`	Tear down every tracked instance.
`instances`	`Map<HTMLElement, AbstractComponent>` of live instances.

`AbstractComponent<TOptions, TElement>`

Member	Description
`el`	The host element.
`options`	Parsed `data-options` object.
`beforeCreate / created / beforeMount / mounted`	Init hooks, called in that order.
`beforeDestroy / destroy`	Teardown hooks.

`ComponentLoader`

new ComponentLoader(registry) — resolves kebab-case names (optionally namespaced) to constructors via the registry. Returns null for unknown names or failed imports. Used internally by ComponentManager; injectable for custom resolution.

`registerAlpineMagic(options?)`

From domwire/alpine. Registers an Alpine magic (default name component, default selector [data-component]) resolving to the nearest instance.

13. Summary

The selector-check init file is one of the most common pieces of accidental architecture in web development: every component asking every page whether it's needed, every page shipping every component, and nothing handling content that arrives late or leaves early. domwire replaces it by letting the markup — the one artifact that already knows what the page contains — drive initialization. One attribute, one registry, one boot call; lazy loading, lifecycle, dynamic-content handling, and error isolation follow from the structure rather than from discipline.

Building a Laravel MCP Server That Answers Questions Over Real Data

Tom Shaw — Thu, 11 Jun 2026 06:59:54 +0000

Building a Laravel MCP Server That Answers Questions Over Real Data

A hands-on guide to the Model Context Protocol in Laravel — from first principles to a live tool inside Claude Desktop

The Model Context Protocol (MCP) lets an AI assistant like Claude call into your application — running your code, reading your data, and answering questions it otherwise couldn't. This tutorial teaches MCP in Laravel by building a working example: a read-only server that answers natural-language questions over a sales database ("who were our top five customers last quarter?") and connecting it to Claude Desktop.

We'll use a sample sales dataset — customers, orders, products, payments — based on the well-known classicmodels sample database (a scale-model car retailer), popularised by MySQL Tutorial and freely available for learning. Nothing here is specific to it, though; the same patterns apply to any Laravel application's data. Every code snippet is an illustrative example; the complete, runnable server is in the accompanying project, linked at the end.

What you'll learn

What MCP is and how it differs from a traditional REST API.
How to test a server locally with the MCP Inspector, before any AI client touches it.
How to make your tools "agent-native" — the small touches that make a server pleasant for a model to use.
How to connect the server to Claude Desktop, and how to secure it for real use.

Part 1 — What is MCP, and how is it different from an API?

An MCP server is, in one sense, an API — it speaks JSON-RPC over a transport and returns structured data. But it's a fundamentally different kind of interface than the REST API you'd hand-write for a single-page app or a mobile client.

The core difference: who the consumer is

A REST API is designed for developers. A human reads the docs, learns the endpoints, and writes code to call GET /orders?status=Shipped. The contract lives in documentation that sits outside the API.
An MCP server is designed for an AI model. The model discovers what's available at runtime by asking the server "what can you do?" The contract is self-describing and ships with the server.

That single shift drives every other difference.

Side by side

	REST API	MCP Server
Consumer	A developer writing code	An AI model, at runtime
Discovery	Read external docs	The server advertises its tools + schemas itself
Description	Docs say how to call it	Each tool says what it does and when to use it
Coupling	Client hard-codes endpoints	Client asks "what can you do?" and adapts
Primitives	Endpoints + HTTP verbs	Tools (actions), Resources (data), Prompts (templates)
Transport/auth	HTTP, you design it	Standardized (stdio / streamable HTTP) — any MCP client connects

The three primitives

A Laravel MCP server is a class that registers three kinds of capability. Here's the skeleton of the server we'll build, which exposes all three:

use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;

#[Instructions(<<<'TXT'
    This server exposes a read-only sales dataset for ad-hoc querying.
    Read the "database-schema" resource first to learn the tables, then
    answer with the curated tools, falling back to a read-only SQL query
    only when no curated tool fits.
    TXT)]
class AssistantServer extends Server
{
    protected array $tools = [
        ListOrdersTool::class,
        SearchCustomersTool::class,
        RevenueReportTool::class,
        RunAssistantQueryTool::class,
        // ...
    ];

    protected array $resources = [DatabaseSchemaResource::class];

    protected array $prompts = [RevenueInsightsPrompt::class];
}

Tools are the callable actions — ListOrdersTool, SearchCustomersTool, and so on. Each is a class with a handle() method, much like a controller action.
Resources are read-only context the model can pull in. Our DatabaseSchemaResource describes every queryable table and column in plain language, so the model knows the shape of the data.
Prompts are reusable templates — RevenueInsightsPrompt seeds a canned analysis workflow.

Notice the #[Instructions] block. It tells the model how to work — read the schema first, prefer curated tools, treat raw SQL as a fallback — and the model receives it automatically on connect. A REST API has no equivalent; the closest thing is a README the developer might never read.

Why this matters

Self-describing & runtime-discoverable. A tool's description ("Lists orders with their status, dates, customer and computed total…") is part of the wire protocol. The model reads it and knows when to reach for the tool — no human gluing docs to code.
One client, any server. Because MCP is a standard, Claude Desktop connects to your Laravel server with zero bespoke integration code. Contrast a REST API, where every consumer writes its own client.
Built for reasoning, not just transport. Descriptions and JSON schemas are written to help a model decide. That's a different design goal than an endpoint that just returns rows.
You keep all your Laravel guts. Tools run inside the app, so they reuse Eloquent, validation, the query builder, config, and auth. You expose your domain to a model without rebuilding it.

The honest trade-offs

Not for browsers or mobile apps. If a human-facing frontend needs the data, a REST/JSON API is still the right tool. MCP targets AI clients.
More machinery for trivial cases. If you just need one endpoint hit by your own SPA, MCP is overkill.
Younger ecosystem. REST tooling (gateways, caching, doc generators) is mature; MCP is newer.

The mental model

A REST API is a menu you read. An MCP server is a waiter who tells you the specials, knows what you can order, and places it for you. Same kitchen (your Laravel app) — a different way of interacting.

A word on data access (read this before you connect anything)

A common worry is "does the model connect to my database?" It does not — it has no connection, no credentials, and can't reach your database at all. The model only ever emits a tool call and reads the JSON your tool returns; your Laravel app is the one holding the connection and running the query.

But here's the part to internalise: for the assistant to answer, your tools must read real rows and return them — and those rows land in the model's context. So the exposure isn't the connection, it's the return values. Any data your tools can read can end up in a conversation, travel to the model provider's API, and be shown to whoever is using the AI client. That reframes what a server's guardrails are really protecting:

Control	Looks like it's for	What it's actually protecting
Read-only DB connection	Preventing writes	The blast radius if a guard is ever bypassed
Table allowlist	Stopping bad SQL	Deciding what data is allowed to leave the building
Blocked column patterns	SQL hygiene	Keeping credentials/PII out of the model's context
Curated tools selecting set columns	Clean output	Not returning columns the model never needs to see

The design principle: scope read access to exactly the data you're willing to put in front of a model. In practice that means a dedicated read-only database user, treating every returned row as data that leaves your perimeter, and authenticating who can reach the server. We'll act on all three in Part 4. The one-liner to remember:

The app needs read access; whatever it reads and returns becomes visible to the model and the user. Scope the read access to what you're willing to expose, and authenticate who can ask.

With the what and the why settled, let's get a server running and prove it works — before any AI client is involved.

Part 2 — Test the server locally with the MCP Inspector

Laravel MCP ships an Inspector: a local web UI that connects to your server and lets you list and call tools, read resources, and watch the raw JSON-RPC traffic. It's the fastest debug loop you have, and the right place to live before you ever open an AI client. First, though, the server has to be reachable.

How a server is exposed

You register a server on a route in routes/ai.php. Our example mounts it as a web (HTTP) server:

use App\Mcp\Servers\AssistantServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/assistant', AssistantServer::class)
    ->middleware(['throttle:mcp']);

That exposes a streamable-HTTP endpoint at /mcp/assistant. The throttle:mcp rate limiter is a plain Laravel limiter — in the example it allows 60 requests/min for an authenticated user, or 20/min by IP otherwise, so the endpoint is reachable in local dev without a token.

Keep the route unauthenticated while you test. The Inspector connects to a web server over HTTP, through the real route — so any auth middleware on it applies. An auth or auth:sanctum guard will reject the Inspector's unauthenticated connection. Register the route with throttle:mcp only for now; we add authentication in Part 4, once the server is ready to expose.

Launch the Inspector

Make sure your app is being served (php artisan serve), then point the Inspector at the server's route or handle:

php artisan mcp:inspector mcp/assistant

This launches the MCP Inspector and opens it in your browser, connected to your running endpoint.

A testing checklist

Work through the server methodically — each step mirrors something the model will do:

List the tools. Confirm they all appear with readable names and descriptions. This is exactly what a model sees on connect — if a description is vague here, the model will misuse the tool there.
Read the schema resource. It should return your curated table/column documentation. The server's instructions tell the model to read this first, so make sure it's clear.
Call a curated tool. Run list-orders with { "status": "Shipped", "limit": 5 }. You should get back JSON with the matching rows.
Exercise validation. Call list-orders with { "status": "Banana" }. You should get a friendly error like "Invalid status. Choose one of: In Process, Shipped, …". Good error text is how a model self-corrects.
Test the raw-SQL guardrails. If your server has an open-ended query tool, call it with a write attempt (DELETE FROM orders) and confirm it's rejected, then a valid SELECT and confirm it runs, then a forbidden table (SELECT * FROM users) and confirm the allowlist blocks it.
Try a prompt. Invoke one and confirm it returns a sensible starter message.

If every item passes, the server is sound.

Tip: keep the Inspector open in a tab while you edit tools. After a change, just re-run a tool call — a far tighter loop than restarting an AI client each time.

Your tools work. But "works" and "pleasant for a model to use" aren't the same thing — and the gap between them is where most of the real craft of an MCP server lives. That's Part 3.

Part 3 — Make the tools "agent-native"

A tool can return correct data and still be hard for a model to use well. The refinements below don't change what a tool does; they change how much the model understands about each call without trial and error — Is it safe to retry? What shape comes back? Did I get all the data? That understanding is the whole "designed for agents" difference. We'll show each as a small before/after.

1. Tool annotations

A read-only tool should say it's read-only. Annotations are metadata the host (the AI client) uses to decide whether a call needs user confirmation, can be safely retried, cached, or run in parallel. Without them, a host has to treat every call as potentially dangerous.

use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Attributes\Description;

#[IsReadOnly]
#[IsIdempotent]
#[Description('Lists orders with their status, dates, customer and computed order total...')]
class ListOrdersTool extends Tool
{
    // ...
}

Add #[IsReadOnly] and #[IsIdempotent] to every read-only tool. For an open-ended SQL tool, add #[IsOpenWorld(false)] to signal it never reaches outside your dataset. This is the cheapest change with the highest signal.

Annotation	Meaning
`#[IsReadOnly]`	The tool does not modify its environment.
`#[IsDestructive]`	The tool may perform destructive updates (only meaningful when not read-only).
`#[IsIdempotent]`	Repeated calls with the same arguments have no additional effect.
`#[IsOpenWorld]`	The tool may interact with external entities.

2. Structured responses + output schemas

A tool that returns Response::text(json_encode($rows)) hands the model a text blob it has to re-parse, and the model can't know the result's shape until after it calls. laravel/mcp has first-class support for structured content:

// Before:
return Response::text(json_encode([
    'row_count' => $rows->count(),
    'rows' => $rows,
], JSON_PRETTY_PRINT));

// After:
return Response::structured([
    'row_count' => $rows->count(),
    'rows' => $rows,
]);

Then declare the shape with an outputSchema() method, so the model knows what it'll get back before it calls:

use Illuminate\Contracts\JsonSchema\JsonSchema;

public function outputSchema(JsonSchema $schema): array
{
    return [
        'row_count' => $schema->integer()->required(),
        'rows' => $schema->array()->description('Matching order rows.'),
    ];
}

Response::structured() keeps a JSON-encoded text fallback for older clients, so you lose nothing.

Note on return types. Response::structured() returns a ResponseFactory, not a Response, so widen the method signature to handle(Request $request): Response|ResponseFactory.

Gotcha — declare nullable fields, or the whole response is rejected. The client doesn't just read your outputSchema, it validates the response against it. If a field can be null — say an optional date you echo back when no range was passed — but you declared it $schema->string(), then null violates "type": "string" and a strict client (Claude Desktop) throws the entire response away with an opaque "Tool execution failed". Your server never errors and your logs stay empty, because the rejection happens client-side. Mark such fields nullable:
'start_date' => $schema->string()->nullable()->description('Start date applied, or null.'),
Telltale sign: the tool works over php artisan mcp:start (the raw client doesn't validate) but fails in Claude Desktop. Inspect exactly what the client sees with (new YourTool)->toArray()['outputSchema'] and check every field whose value can be null.

3. Drop `JSON_PRETTY_PRINT` — token economy

Models pay per token, and pretty-printing pads every response with whitespace the model doesn't need. Response::structured() handles encoding for you, so this disappears the moment you adopt #2 — but it's worth stating as its own principle: for a model, terse beats pretty. The same applies to any resource that hand-encodes JSON.

4. Signal truncation — a real design gap

Capping a result set (LIMIT 50, a clampLimit() helper) silently hides rows. If 50 come back, the model can't tell whether that's the whole answer or a wall it hit — so it may reason on incomplete data. Fetch one extra row to detect the cap, and tell the model:

$limit = $this->clampLimit($validated['limit'] ?? null, 50);

$rows = $query->limit($limit + 1)->get();    // one extra to detect "more"
$truncated = $rows->count() > $limit;

return Response::structured([
    'row_count' => min($rows->count(), $limit),
    'truncated' => $truncated,                // model now knows to narrow filters or page
    'rows'      => $rows->take($limit)->values(),
]);

5. Use real schema `->default()` values

Documenting "(default 50)" in prose leaves the value in text the model has to interpret. ->default(50) is machine-readable — something the client can act on directly:

'limit' => $schema->integer()
    ->default(50)
    ->description('Maximum number of orders to return.'),

6. Gate your highest-risk tool

An open-ended SQL tool is the one surface where the guardrails are the security boundary. You can expose it only to authorized users with shouldRegister(), which runs per request — a tool that returns false never appears in the tool list and can't be invoked:

public function shouldRegister(Request $request): bool
{
    return $request?->user()?->can('run-raw-queries') ?? false;
}

(This requires an authenticated route and a matching ability — see Part 4.)

The takeaway

None of this changes what the server does. It changes how much the model understands about each call — read-only? retry-safe? what shape comes back? did I get everything? — without finding out the hard way. Items #1–#4 are the high-value set.

Test every change. Each refinement is easy to cover: assert the new truncated key, assert the structured output, assert a tool carries its annotations. A server you can't test, you can't trust in front of a model.

Your server is correct and agent-friendly. Time to put it in front of Claude.

Part 4 — Connect the server to Claude Desktop

Claude Desktop launches MCP servers as local processes that speak over stdio. Our server is a web (HTTP) server, so we bridge the two with mcp-remote — a tiny npm tool that proxies Claude Desktop's stdio to an HTTP endpoint. No code change required.

Step 1 — Start the server yourself, and keep it running

This is the step that trips people up. With the web + mcp-remote setup, Claude Desktop only launches the bridge — it does not start your Laravel app. So you have to run the server manually and leave it running for the whole session:

php artisan serve     # or your usual dev command (composer run dev, Sail, Herd, etc.)

Confirm the endpoint is live (e.g. http://localhost:8000/mcp/assistant). If the app isn't running, the bridge connects to a dead URL and the tools never appear in Claude.

Why manual, when other MCP servers "just start"? A server registered with Mcp::local(...) is launched by Claude Desktop itself — the config runs php artisan mcp:start <handle> over stdio, so there's nothing to start by hand. A web server (Mcp::web) is the opposite: it's a normal HTTP endpoint that has to be up before the client connects. (See Two ways to connect at the end of this part for the local/stdio alternative.)

Step 2 — Open the Claude Desktop config

In Claude Desktop: Settings → Developer → Edit Config. That opens claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3 — Add the server

Add an entry under mcpServers. The key (laravel-assistant) is the display name; the command runs mcp-remote pointed at your endpoint:

{
  "mcpServers": {
    "laravel-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp/assistant"
      ]
    }
  }
}

If you already have other servers in mcpServers, add laravel-assistant alongside them — don't replace the whole object.

Step 4 — Restart Claude Desktop

Fully quit and reopen Claude Desktop (a window reload isn't enough — it spawns the server processes on launch). When it comes back, your tools appear in the chat's tool menu.

Step 5 — Try it

Ask Claude a question your server can answer from its data:

"Using the Assistant tools, what were our top 5 customers by revenue, and which sales rep owns each?"

Claude reads the schema resource, picks the right tool (or composes a read-only SELECT), and answers from your live data — exactly the workflow the #[Instructions] block describes.

Securing it for real use

The setup above is unauthenticated — fine for localhost, dangerous anywhere else. Never expose an unauthenticated MCP server publicly; it's a direct line to your data. Two things make it production-safe.

1. Authenticate who can ask. Protect the route and pass a token from the client:

// routes/ai.php — protect with Sanctum
Mcp::web('/mcp/assistant', AssistantServer::class)
    ->middleware(['auth:sanctum', 'throttle:mcp']);

// claude_desktop_config.json — pass the bearer token through the bridge
{
  "mcpServers": {
    "laravel-assistant": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-app.com/mcp/assistant",
        "--header", "Authorization: Bearer YOUR_SANCTUM_TOKEN"
      ]
    }
  }
}

For the broadest client compatibility, laravel/mcp also supports OAuth 2.1 via Laravel Passport (Mcp::oauthRoutes() + auth:api middleware), the mechanism the MCP spec recommends. Reach for it when you need to support clients that only speak OAuth.

2. Scope what the app can read. Authentication decides who can ask; the database grant decides what the app can read on their behalf. As Part 1 covered, every returned row leaves your perimeter — so the read-only user behind your assistant connection should hold SELECT on only the tables you mean to expose. The application guardrails are your first line; a scoped grant is the backstop if one is ever bypassed.

CREATE USER 'assistant_ro'@'%' IDENTIFIED BY 'a-strong-password';

GRANT SELECT ON app_db.customers     TO 'assistant_ro'@'%';
GRANT SELECT ON app_db.orders        TO 'assistant_ro'@'%';
GRANT SELECT ON app_db.order_details TO 'assistant_ro'@'%';
GRANT SELECT ON app_db.products      TO 'assistant_ro'@'%';
GRANT SELECT ON app_db.payments      TO 'assistant_ro'@'%';
-- ...one line per table you expose; nothing else.

FLUSH PRIVILEGES;

Point the assistant connection at that user, then verify the grant from the database's side — don't trust the config comment, check it:

# Every line should be SELECT on a table you intend to expose —
# no other tables, no INSERT/UPDATE/DELETE, no schema-wide "app_db.*".
mysql -u root -p -e "SHOW GRANTS FOR 'assistant_ro'@'%';"

# And confirm the negative cases are denied:
mysql -u assistant_ro -p app_db -e "DELETE FROM orders LIMIT 1;"   # must fail
mysql -u assistant_ro -p app_db -e "SELECT * FROM users LIMIT 1;"  # must fail

If a write or a non-exposed table succeeds, the grant is too broad — fix it before going live. A scoped grant means even a bug in your query guard can only ever read the tables you already chose to expose. (For zero impact on production load, point it at a read replica.)

Two ways to connect

We used a web server plus the mcp-remote bridge because it's the same endpoint you'd authenticate and deploy for real. But Laravel MCP supports a second transport that's often simpler for purely local use:

	Web (`Mcp::web`, used above)	Local / stdio (`Mcp::local`)
Who starts the server	You do — `php artisan serve`, kept running	Claude Desktop does — it runs the command for you
Client config	`npx mcp-remote <url>`	`php artisan mcp:start <handle>`
Auth	Sanctum / OAuth over HTTP	Inherits your CLI environment
Best for	Shared/remote access, production	One developer, one machine

To use the local transport, register the server with Mcp::local('assistant', AssistantServer::class) in routes/ai.php, then have Claude Desktop launch it directly:

{
  "mcpServers": {
    "laravel-assistant": {
      "command": "/opt/homebrew/bin/php",
      "args": [
        "/absolute/path/to/your-app/artisan",
        "mcp:start",
        "assistant"
      ]
    }
  }
}

Use absolute paths. Claude Desktop doesn't inherit your shell's PATH, so "command": "php" will usually fail to launch. Point at the full binary (which php → e.g. /opt/homebrew/bin/php) and the full path to your project's artisan. With this transport there's nothing to start by hand — Claude Desktop spawns the process — but you trade away the HTTP auth story from the previous section.

You've gone the full loop:

understood MCP as a self-describing interface built for models, not developers;
tested a server in isolation with the Inspector;
made the tools agent-native with annotations, structured output, and truncation signalling;
connected it to Claude Desktop and locked down both who can ask and what the app can read.

The same patterns scale to any Laravel application: expose your domain as a handful of well-described tools, return structured data, and be deliberate about what leaves your perimeter.

Get the code. The complete, runnable server used throughout this tutorial — every tool, the schema resource, the prompt, and the test suite — is in the accompanying project: laravel-mcp-demo

Building a Streaming LLM Agent with the Laravel AI SDK

Tom Shaw — Sun, 07 Jun 2026 05:09:27 +0000

Building a Streaming LLM Agent with the Laravel AI SDK

A raw language model is a closed book. It can write, reason, and explain, but it
only knows what it absorbed during training, and it can only ever produce text.
Ask it the current time, today's exchange rate, an exact arithmetic result, or
anything that changed last week, and it has two choices: admit it doesn't know,
or guess convincingly. Neither is what you want in a product.

The fix is to stop treating the model as an oracle and start treating it as the
reasoning core of a larger system — one that can take actions, see what comes
back, and reason again. That system is what we call an agent, and this guide
walks through building a real one: a streaming chat assistant that calls tools,
remembers conversations, and renders its answer token by token in the browser.

Agents, and the Laravel AI SDK

The intro called that system an agent. Here is the idea precisely. An LLM agent
is a language model wrapped in a loop that lets it act on the world instead of
answering in a single shot. The model is no longer just predicting the next token
of a reply — at each step it decides whether it has enough information to answer,
or whether it needs to reach for a tool.

The dominant pattern for this is ReAct — short for Reasoning +
Acting. Rather than answering all at once, the model works through a cycle:

Reason — think about what the question actually requires.
Act — if it needs outside information, call a tool (a function you provide) instead of guessing.
Observe — the tool runs and returns a result, which is fed back to the model as a new observation.
Repeat — the model reasons about that observation and either calls another tool or produces its final answer.

A worked example — "What time is it in Tokyo right now?":

User:    What time is it in Tokyo right now?

Reason:  I don't actually know the current time. I should call a clock tool.
Act:     current_datetime(timezone: "Asia/Tokyo")
Observe: Saturday, June 6, 2026 at 11:42 PM (Asia/Tokyo)
Reason:  I now have the real local time. I can answer.
Answer:  It's currently 11:42 PM on Saturday, June 6, 2026 in Tokyo.

The key move is that the model never fakes the time. It recognises the gap in
its knowledge, reaches for a tool, and reasons over the real result. That loop —
reason, act, observe, repeat — is the entire idea behind an agent.

Building one by hand, though, means solving the same set of problems every time:
speaking each provider's particular HTTP dialect, describing tools in a format the
model understands, parsing tool calls back out of the response, driving the
reason/act/observe loop, and threading conversation history through all of it. The
Laravel AI SDK (laravel/ai) is the first-party package that solves those
problems once, behind an API that feels like the rest of Laravel.

The shift it asks you to make is this: you stop writing procedural code that
calls an API, and you start describing an agent as a class. A system prompt, a
model, and a list of tools become declarations on a PHP class; the SDK reads that
class and does the orchestration. It speaks to every major provider — Anthropic,
OpenAI, Gemini, Groq, Ollama — through the same interface, so switching models is
a one-line change rather than a rewrite.

Until recently, that kind of tooling lived almost entirely in Python — LangChain,
LlamaIndex, the provider-native agent frameworks. For a Laravel team, adopting
them means standing up a second service in a second language and talking to it
over HTTP, which quietly puts your AI logic on the wrong side of a boundary: away
from your Eloquent models, your auth gates, your queue, and your test suite.

This is where the Laravel AI SDK is genuinely hard to beat — and it isn't about
cleverer abstractions. It's that the agent lives inside your application. A tool
is just PHP, so it can query Eloquent, respect a Gate, or dispatch a job directly.
Persistence is migrations and Eloquent models. Streaming rides Livewire. Tests use
the same Pest fakes as everything else. There's no glue service and no
serialization boundary to cross — the model's reasoning and your domain logic run
in the same process, with the same tools you already know.

Each thing an agent needs maps onto a concept the SDK gives you:

The agent itself is a class you prompt. It carries the instructions, the model choice, and the tools, and exposes methods like prompt() and stream().
A tool is a capability you grant that agent — a class with a name, a description, a parameter schema, and a handle() method that does the work.
Streaming lets you consume the reply as it forms, as a sequence of typed events (text fragments, tool calls) rather than one final blob.
Conversation memory persists each turn and replays prior history, so a multi-turn chat just works without you managing state by hand.

The single most important thing the SDK does, though, is run the agent loop for
you. You hand it tools and a step limit; it asks the model what it wants to do,
executes the chosen tool, feeds the result back, and repeats until the model has
a final answer. The whole ReAct cycle happens inside the SDK — you never write the
loop yourself.

It's built on Prism

The SDK doesn't reinvent provider communication from scratch. Underneath, it's
built on Prism, and the two relate the way
Eloquent relates to the Query Builder: Prism is the lower-level engine that
normalises providers and raw LLM calls, and the Laravel AI SDK is the
higher-level, opinionated framework on top — the layer that adds agents, tools,
memory, structured output, streaming, and testing helpers.

That layering is concrete, not just a metaphor: laravel/ai declares
prism-php/prism as a Composer dependency, so a call to $agent->stream()
ultimately drives Prism, which drives the provider's HTTP API:

Your app  →  Laravel AI SDK  →  Prism  →  Anthropic / OpenAI / …
            (agents, tools,     (provider
             memory, streaming)  normalisation)

The practical guidance follows directly from that: build on the Laravel AI SDK.
It's the layer meant for application code, and it's where everything in this guide
lives. Knowing Prism is underneath is useful — if you ever need something the SDK
hasn't surfaced yet, you can drop down to it directly, exactly as you'd
occasionally reach past Eloquent for the Query Builder.

Configuration

Stack: PHP 8.5 · Laravel 13 · Livewire 4 · Laravel AI SDK

Enough theory — let's wire it up, starting with the one piece of setup the SDK
can't infer: where to send requests, and with what key. Both live in your
environment. We'll use Anthropic throughout, but any supported provider works the
same way:

# .env
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

config/ai.php reads those values. The default provider falls back to
anthropic, and the Anthropic driver is wired to the API key:

// config/ai.php
'default' => env('AI_PROVIDER', 'anthropic'),

'providers' => [
    // ...
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_URL', 'https://api.anthropic.com/v1'),
    ],
    // ...
],

You rarely reference the string 'anthropic' in code, though. The SDK ships a
type-safe Lab enum (Laravel\Ai\Enums\Lab) that you attach to an agent — which
is exactly what we'll do next.

Building the agent

An agent is one small class. Read it once, then we'll break it down.

// ChatAgent.php
use App\Ai\Tools\Calculator;
use App\Ai\Tools\CurrentDateTime;
use App\Ai\Tools\WikipediaLookup;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;
use Laravel\Ai\Providers\Tools\WebSearch;
use Stringable;

#[Provider(Lab::Anthropic)]
#[Model('claude-sonnet-4-6')]
#[Temperature(0.7)]
#[MaxSteps(8)]
class ChatAgent implements Agent, Conversational, HasTools
{
    use Promptable, RemembersConversations;

    public function instructions(): Stringable|string
    {
        return <<<'PROMPT'
        You are a friendly, knowledgeable assistant that answers using the ReAct pattern:
        Reason about the question, Act by calling a tool when it helps, observe the
        result, then continue until you can give a clear final answer.

        Guidelines:
        - Think step by step, but keep your final answer concise and well formatted (Markdown).
        - Use the `calculator` tool for any arithmetic instead of computing in your head.
        - Use the `current_datetime` tool whenever the user asks about the current date or time.
        - Use the `wikipedia_lookup` tool for factual background on a specific topic, person, or place.
        - Use web search for recent events or anything that may have changed after your training.
        - If a tool fails or returns nothing useful, say so honestly rather than guessing.
        PROMPT;
    }

    public function tools(): iterable
    {
        return [
            new Calculator,
            new CurrentDateTime,
            new WikipediaLookup,
            (new WebSearch)->max(5),
        ];
    }
}

The attributes

PHP attributes configure the agent declaratively:

#[Provider(Lab::Anthropic)] — which provider to talk to, using the type-safe Lab enum rather than a magic string.
#[Model('claude-sonnet-4-6')] — the specific model.
#[Temperature(0.7)] — sampling randomness; 0.7 is a balanced default for a conversational assistant.
#[MaxSteps(8)] — the ReAct loop bound. Each "step" is one reason→act→observe cycle. With 8, the agent may call tools and reason up to eight times before it must produce a final answer. This is your safety valve against a model that loops forever calling tools.

The contracts and traits

class ChatAgent implements Agent, Conversational, HasTools
{
    use Promptable, RemembersConversations;

implements Agent — marks the class as an agent.
implements HasTools — declares that this agent exposes tools (via tools()).
implements Conversational — declares that this agent participates in persisted, multi-turn conversations.
use Promptable — adds the prompt() and stream() methods you call to run the agent.
use RemembersConversations — automatically persists each user/assistant turn and replays prior history so the model has context. Conversation memory, for free.

The system prompt

instructions() returns the system prompt, and it's doing two jobs at once: it
tells the model to follow the ReAct pattern, and it gives concrete guidance on
which tool to prefer for which kind of question. Good tool descriptions plus
clear prompt guidance are what make the model reach for the right tool at the
right time.

The tools

tools() returns the list the model is allowed to call. Three are custom classes
(Calculator, CurrentDateTime, WikipediaLookup); the fourth, WebSearch, is
a built-in provider tool shipped by the SDK — capped here to five results
with ->max(5). Let's write one.

Writing tools

A tool is any class implementing Laravel\Ai\Contracts\Tool. The contract is
four methods: name(), description(), schema(), and handle(). The model
reads the name, description, and schema to decide whether and how to call the
tool; handle() does the actual work and returns an observation string.

A minimal tool: the current date and time

The clock is the cleanest example of an "observation" tool — the model simply
cannot know the real current time, so it has to ask.

// CurrentDateTime.php
use Carbon\CarbonImmutable;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class CurrentDateTime implements Tool
{
    public function name(): string
    {
        return 'current_datetime';
    }

    public function description(): Stringable|string
    {
        return 'Get the current date and time. Optionally pass an IANA timezone '
            .'(e.g. "Asia/Tokyo", "America/New_York") to get the local time there.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'timezone' => $schema->string()
                ->description('An IANA timezone identifier such as "Europe/Paris". Defaults to UTC.'),
        ];
    }

    public function handle(Request $request): Stringable|string
    {
        $timezone = $request->string('timezone', 'UTC')->toString();

        if (! in_array($timezone, timezone_identifiers_list(), true)) {
            return "Unknown timezone \"{$timezone}\". Please use an IANA identifier like \"Asia/Tokyo\".";
        }

        $now = CarbonImmutable::now($timezone);

        return $now->format('l, F j, Y \a\t g:i A').' ('.$timezone.')';
    }
}

Worth noticing:

name() is the identifier the model uses when it decides to call the tool. Keep it short and snake_case.
description() is sales copy aimed at the model. The clearer you describe when to use the tool and what each parameter means, the more reliably the model calls it correctly.
schema() declares the parameters using a fluent JSON-schema builder. Here, timezone is an optional string (no ->required()), with its own description so the model knows to pass an IANA identifier.
handle(Request $request) receives the model's arguments as a Request object. $request->string('timezone', 'UTC') reads the argument with a default. The returned string is what the model "observes." Note that we validate the timezone and return a helpful message instead of throwing — the model can read that message and recover.

A tool that calls an external API

Tools can do real I/O. This one reaches out to Wikipedia's REST API and returns a
summary — and, importantly, it handles every failure path gracefully so the model
always gets a usable observation.

// WikipediaLookup.php
public function schema(JsonSchema $schema): array
{
    return [
        'topic' => $schema->string()
            ->description('The Wikipedia article title to summarize, e.g. "Great Barrier Reef".')
            ->required(),
    ];
}

public function handle(Request $request): Stringable|string
{
    $topic = $request->string('topic')->trim()->toString();

    if ($topic === '') {
        return 'No topic was provided to look up.';
    }

    try {
        $response = Http::acceptJson()
            ->withHeaders(['User-Agent' => 'LaravelAiSdkDemo/1.0 (tutorial)'])
            ->timeout(15)
            ->get('https://en.wikipedia.org/api/rest_v1/page/summary/'.rawurlencode($topic));
    } catch (Throwable $e) {
        return "Wikipedia lookup for \"{$topic}\" failed: {$e->getMessage()}";
    }

    if ($response->status() === 404) {
        return "No Wikipedia article was found for \"{$topic}\".";
    }

    if ($response->failed()) {
        return "Wikipedia lookup for \"{$topic}\" failed with status {$response->status()}.";
    }

    $extract = $this->jsonString($response, 'extract');

    if ($extract === '') {
        return "No summary is available for \"{$topic}\".";
    }

    $title = $this->jsonString($response, 'title', $topic);
    $url = $this->jsonString($response, 'content_urls.desktop.page');

    return trim("**{$title}**\n{$extract}".($url !== '' ? "\nSource: {$url}" : ''));
}

The pattern here is the lesson: a tool should never throw raw exceptions at
the model. A timeout, a 404, an empty body — each becomes a plain-English string
the model can reason about ("the lookup failed, I'll tell the user honestly"),
exactly as the system prompt instructs. Note that topic is ->required(), and
the tool returns lightly-formatted Markdown including a source link.

A tool that must be safe: the calculator

A calculator lets the model do exact arithmetic. The interesting part is what it
doesn't do — it never calls eval(). Instead it tokenizes the expression and
walks a tiny recursive-descent grammar that only understands numbers, the
operators + - * / % ^, parentheses, and unary minus. Anything else is rejected.

// Calculator.php
public function schema(JsonSchema $schema): array
{
    return [
        'expression' => $schema->string()
            ->description('The arithmetic expression to evaluate, e.g. "3 * (4 + 5)".')
            ->required(),
    ];
}

public function handle(Request $request): Stringable|string
{
    $expression = $request->string('expression')->toString();

    try {
        $result = $this->evaluate($expression);
    } catch (Throwable $e) {
        return "Could not evaluate \"{$expression}\": {$e->getMessage()}";
    }

    // Render integers without a trailing ".0" for nicer output.
    $formatted = $result == (int) $result
        ? (string) (int) $result
        : (string) $result;

    return "{$expression} = {$formatted}";
}

The takeaway: model-supplied input is untrusted. A naive eval($expression)
would be a remote code execution hole, because the model (or a user steering it)
controls that string. A private evaluate() method that parses safely is the
right call. The same principle applies any time a tool touches your filesystem,
your shell, or your database — treat the arguments as adversarial.

Built-in provider tools

Not every tool is yours to write. (new WebSearch)->max(5) from earlier is a
provider tool (Laravel\Ai\Providers\Tools\WebSearch) — the provider runs the
search natively. You compose it alongside your custom tools in the same list, and
the model treats them all the same way.

Streaming the answer to the browser

Tools and the agent loop are the brain; streaming is how the user actually
experiences it. Rather than blocking until the full answer is ready, you iterate
over the response and push fragments to the browser as they arrive.

Here's the heart of it — a component method that takes a prompt, runs the agent,
and streams the reply:

use App\Ai\Agents\ChatAgent;
use Laravel\Ai\Streaming\Events\TextDelta;
use Laravel\Ai\Streaming\Events\ToolCall;

public function send(string $prompt): void
{
    $prompt = trim($prompt);

    if ($prompt === '') {
        return;
    }

    // The ReAct loop streams over a long-lived request (tool calls, web
    // search, multi-step reasoning); lift the request time limit so the
    // response isn't truncated mid-stream by PHP's max_execution_time.
    set_time_limit(0);

    $agent = $this->conversationId === null
        ? ChatAgent::make()->forUser($this->user())
        : ChatAgent::make()->continue($this->conversationId, as: $this->user());

    $response = $agent->stream($prompt);

    $answer = '';

    foreach ($response as $event) {
        if ($event instanceof ToolCall) {
            $this->stream(to: 'status', content: 'Using '.$event->toolCall->name.'…', replace: true);
        } elseif ($event instanceof TextDelta) {
            // Render the accumulated answer as Markdown on each delta so the
            // live stream shows formatted text (not raw Markdown), matching
            // how the persisted message is rendered once the turn completes.
            $answer .= $event->delta;

            $this->stream(
                to: 'answer',
                content: Str::markdown($answer, ['html_input' => 'escape', 'allow_unsafe_links' => false]),
                replace: true,
            );
        }
    }

    // After the stream finishes, the SDK has persisted the conversation.
    $this->conversationId = $response->conversationId;

    unset($this->messages);

    $this->dispatch('conversation-updated', id: $this->conversationId);
}

Step by step:

set_time_limit(0) — a ReAct turn can involve several tool calls and a web
search, so it may outlast PHP's default max_execution_time. Lifting the
limit prevents the stream from being cut off mid-answer.
Starting vs continuing a conversation — ChatAgent::make() builds the
agent. ->forUser($user) starts a new conversation owned by that user;
->continue($conversationId, as: $user) resumes an existing one so the model
sees prior history. The component just tracks a conversationId.
$agent->stream($prompt) — runs the agent and returns an iterable stream
instead of a single blob. The Promptable trait provides this.
The event loop — iterating the response yields typed events:
- ToolCall — the model decided to act. Surface a small "Using calculator…" status so the user can see the agent reaching for a tool; $event->toolCall->name is the tool's name().
- TextDelta — a fragment of the final answer. Accumulate fragments into $answer, render the running total as Markdown, and push it to the answer target with replace: true (replace, not append, because we re-render the whole accumulated Markdown each time).
After the loop — because of RemembersConversations, the SDK has already
persisted both the user prompt and the assistant reply. Read the (possibly
brand-new) conversationId back off the response and refresh the UI.

Where the stream lands in the markup

Streaming to a named target (to: 'answer', to: 'status') maps onto regions in
the view via wire:stream:

<div x-show="streaming" x-cloak class="flex flex-col gap-2">
    <div x-ref="status" wire:stream="status" class="text-xs font-medium text-accent"></div>
    <div class="max-w-[90%] text-[15px]">
        <span x-show="!hasAnswer" class="inline-flex gap-1 align-middle">
            {{-- animated "typing" dots while we wait for the first token --}}
        </span>
        <div x-ref="answer" wire:stream="answer" class="reply" :class="hasAnswer && 'stream-caret'"></div>
    </div>
</div>

The wire:stream="answer" element receives each streamed update directly in the
browser — no full round-trip per token. A small amount of client-side JavaScript
handles the niceties: showing the user's question optimistically the instant they
hit send, disabling the composer while streaming, auto-scrolling as the reply
grows, and resetting on a conversation switch.

The result: the user sees a "Using calculator…" pill, then the answer typing
itself out live, then a clean persisted message — all from a single method.

Persisting conversations

Notice there was no persistence code in send() — the SDK handled it. Three
pieces make that work.

1. The user owns conversations. The User model uses the SDK's
HasConversations trait, which is what makes ->forUser($user) and
->continue(..., as: $user) work:

use Laravel\Ai\Concerns\HasConversations;

class User extends Authenticatable
{
    use HasConversations, HasFactory, Notifiable;
    // ...
}

2. The agent remembers. The RemembersConversations trait on the agent is
what actually writes each turn and replays history.

3. The schema. A migration extending Laravel\Ai\Migrations\AiMigration
creates two tables — one for conversations, one for messages:

return new class extends AiMigration
{
    public function up(): void
    {
        $conversationsTable = config('ai.conversations.tables.conversations', 'agent_conversations');
        $messagesTable = config('ai.conversations.tables.messages', 'agent_conversation_messages');

        Schema::create($conversationsTable, function (Blueprint $table) {
            $table->string('id', 36)->primary();
            $table->foreignId('user_id')->nullable();
            $table->string('title');
            $table->timestamps();

            $table->index(['user_id', 'updated_at']);
        });

        Schema::create($messagesTable, function (Blueprint $table) {
            $table->string('id', 36)->primary();
            $table->string('conversation_id', 36)->index();
            $table->foreignId('user_id')->nullable();
            $table->string('agent');
            $table->string('role', 25);
            $table->text('content');
            $table->text('attachments');
            $table->text('tool_calls');
            $table->text('tool_results');
            $table->text('usage');
            $table->text('meta');
            $table->timestamps();

            $table->index(['conversation_id', 'user_id', 'updated_at'], 'conversation_index');
            $table->index(['user_id']);
        });
    }
    // ...
};

Each message row stores the role (user / assistant / tool), the
content, and — useful for a UI — the tool_calls the assistant made. That's how
you can render a "calculator" pill next to a persisted answer: read the saved
tool_calls for that message. You query these through the SDK's
Laravel\Ai\Models\Conversation and Laravel\Ai\Models\ConversationMessage
Eloquent models.

Testing

A feature with this many moving parts — streaming, tool calls, persistence —
needs tests, and the obvious approach is the wrong one: hitting a real model in
tests would be slow, costly, and non-deterministic. Instead, the SDK provides a
fake() helper to swap the agent for a scripted response, plus assertions to
verify it was prompted correctly.

it('streams an answer and persists the conversation', function () {
    ChatAgent::fake(['Hello from the agent!']);

    $component = Livewire::test('chat.main', ['userId' => $this->user->id])
        ->call('send', 'Hi there')
        ->assertSee('Hi there')
        ->assertSee('Hello from the agent!')
        ->assertDispatched('conversation-updated');

    expect($component->get('conversationId'))->not->toBeNull();

    ChatAgent::assertPrompted('Hi there');

    expect(ConversationMessage::where('role', 'user')->count())->toBe(1)
        ->and(ConversationMessage::where('role', 'assistant')->count())->toBe(1);
});

What this verifies, end to end:

ChatAgent::fake(['Hello from the agent!']) makes the agent return a canned reply instead of calling the provider.
The flow renders both the user's prompt and the agent's reply, and dispatches the conversation-updated event.
ChatAgent::assertPrompted('Hi there') confirms the agent received the exact prompt.
Both the user and assistant messages were persisted — proving the RemembersConversations wiring works.

There's a matching assertNotPrompted() for the "ignore blank prompts" case, and
tools are best covered by fast unit tests that exercise their handle() logic and
error paths directly — no model needed. Run the suite with:

php artisan test --compact

Extending it: add your own tool

Once the agent is in place, growing its capabilities is a tight, three-step loop:

Create the tool. php artisan make:tool MyTool scaffolds a class. Implement name(), description(), schema(), and handle() — model the description/schema text carefully, since that's how the model decides to call it. Return plain strings, including for errors.
Register it in the agent's tools() method by adding new MyTool to the array.
Optionally mention it in the agent's instructions() so the model knows when to prefer it, and test it with a unit test plus a faked-agent feature test.

That's the entire workflow. The SDK handles the reasoning, the tool calls, the
streaming, and the persistence; you provide a well-described agent and a handful
of safe, honest tools — and the ReAct pattern does the rest.

Source code

Everything in this guide comes together in a complete, runnable application — a
minimal ChatGPT-style assistant with a streaming UI, the four tools shown above,
conversation history, and the full test suite. You can clone it, add your API
key, and have a working agent in a few minutes:

Tom Shaw / laravel-aisdk-demo

Concern	File
The agent	`app/Ai/Agents/ChatAgent.php`
Tools	`app/Ai/Tools/*.php`
Chat UI + streaming	`resources/views/components/chat/⚡main.blade.php`
Conversation owner	`app/Models/User.php`
Persistence schema	`database/migrations/..._create_agent_conversations_table.php`
Config	`config/ai.php`
Tests	`tests/Feature/ChatTest.php`, `tests/Unit/*`

Clone it, read the agent class first, then follow a single prompt through
send() and watch the reason/act/observe loop play out token by token.

DEV Community: Tom Shaw

Wiring components to server-rendered pages with domwire

1. The problem

Why this is fundamentally awkward

2. The idea behind domwire

3. Getting started

Install

Write a component

Declare it in markup

Boot

4. Passing options

5. The lifecycle

6. Dynamic content: observe()

7. Lazy loading in depth

8. Namespaces

9. Error handling

10. Accessing instances and interop

Alpine.js integration

11. Why this approach

Against the manual selector-check pattern

Against adopting a framework

Against Web Components / custom elements

Against jQuery-style plugins

The cost

12. API reference

ComponentManager

AbstractComponent<TOptions, TElement>

ComponentLoader

registerAlpineMagic(options?)

13. Summary

Building a Laravel MCP Server That Answers Questions Over Real Data

Building a Laravel MCP Server That Answers Questions Over Real Data

A hands-on guide to the Model Context Protocol in Laravel — from first principles to a live tool inside Claude Desktop

Part 1 — What is MCP, and how is it different from an API?

The core difference: who the consumer is

Side by side

The three primitives

Why this matters

The honest trade-offs

The mental model

A word on data access (read this before you connect anything)

Part 2 — Test the server locally with the MCP Inspector

How a server is exposed

Launch the Inspector

A testing checklist

Part 3 — Make the tools "agent-native"

1. Tool annotations

2. Structured responses + output schemas

3. Drop JSON_PRETTY_PRINT — token economy

4. Signal truncation — a real design gap

5. Use real schema ->default() values

6. Gate your highest-risk tool

The takeaway

Part 4 — Connect the server to Claude Desktop

Step 1 — Start the server yourself, and keep it running

Step 2 — Open the Claude Desktop config

Step 3 — Add the server

Step 4 — Restart Claude Desktop

Step 5 — Try it

Securing it for real use

Two ways to connect

Building a Streaming LLM Agent with the Laravel AI SDK

Building a Streaming LLM Agent with the Laravel AI SDK

Agents, and the Laravel AI SDK

It's built on Prism

Configuration

Building the agent

The attributes

The contracts and traits

The system prompt

The tools

Writing tools

A minimal tool: the current date and time

A tool that calls an external API

A tool that must be safe: the calculator

Built-in provider tools

Streaming the answer to the browser

Where the stream lands in the markup

Persisting conversations

Testing

6. Dynamic content: `observe()`

`ComponentManager`

`AbstractComponent<TOptions, TElement>`

`ComponentLoader`

`registerAlpineMagic(options?)`

3. Drop `JSON_PRETTY_PRINT` — token economy

5. Use real schema `->default()` values