Open Source / laravel-swarm-mcp
Point any AI client at your swarms.
A read-only Model Context Protocol server for Swarm. It exposes your run history, durable-run state, and audit health as MCP resources — so Claude, Cursor, or any MCP client can inspect what your agents did. It reads your persisted run data; it never touches it.
Install
composer require builtbyberry/laravel-swarm-mcpAt a glance
Companion · MIT
Built on — laravel/mcp ^0.8 · PHP 8.5+
Pairs with — laravel-swarm ^0.19
Surface — Read-only resources
Transports — stdio · HTTP (Sanctum)
Namespace — BuiltByBerry\LaravelSwarmMcp
Why it exists
Swarm records everything. This makes it addressable by AI.
Swarm persists every step, tool call, and retry so agentic work is auditable by default. The agents that would most benefit from reading that trail speak one protocol already.
This server exposes the trail as Model Context Protocol resources — the same protocol Claude and Cursor already speak — so an AI client can inspect a run without a bespoke API to build or a dashboard to stand up.
01
Resource-addressable
Runs, durable state, and audit health are URI-addressable MCP resources — swarm://runs/{id}, not a query you hand-write.
02
Read-only by design
It registers zero tools. An agent can observe a run; it can never pause, resume, cancel, or signal one. Control is a deliberate later minor.
03
Native to laravel/mcp
Built on Laravel's official MCP package — stdio and HTTP transports, same auth, same conventions. Register it and the resources appear.
What it exposes
Six resources, one URI namespace.
swarm://runs # recent runs, decryption-free
swarm://runs/{runId} # one run + its steps
swarm://durable-runs/{runId} # assembled durable-run state
swarm://audit-outbox/health # outbox availability + counts
swarm://audit-outbox/queue/{state} # pending | dead-lettered
swarm://audit-outbox/records/{id} # one row, full payloadRun history
Every run, list to detail
A decryption-free list of recent runs, and a per-run resource with its steps, inputs, outputs, and timing — the whole trail, one URI at a time.
Durable inspection
The shape of a long-running run
Assembled durable-run state — waits, signals, progress, child runs, branches, and hierarchical outputs — so an agent can reason about where a workflow actually is.
Audit outbox
Is delivery healthy
Outbox health, the pending and dead-lettered queues, and a single row's full payload on demand — pure reads that never drain the outbox the relay drains.
Display-safe
Degrades, never leaks
Sealed fields are decrypted per field. An undecryptable value — a rotated key, a poison row — comes back as null with an *_available: false flag, never raw ciphertext, never a failed read.
The trust surface
A window, not a lever.
Handing an autonomous agent a read into production data has to earn its access. This one is built to. It reads through Swarm's public display contracts — never a mutating call, never the internal cipher — and exposes no tool that could change a run.
Reads through contracts
Sources persisted run data through core's public read interfaces only. It cannot write, and it cannot reach the sealed internals.
Zero tools
The server declares no tools and no prompts — a fail-safe, resources-only surface. There is no verb an agent could call to act on a run.
Sealed values stay masked
Encrypted payloads route through a display chokepoint that degrades per field and masks ciphertext — no accidental leak into a client.
Authenticated transport
The HTTP transport sits behind your auth (Sanctum by default). Which runs a caller may read stays your application's call.
Get started
Two steps to an MCP server.
You need laravel-swarm ^0.19 with database persistence enabled. The server reads what Swarm already stores — no tables and no migrations of its own.
Step 01
Install
Pull the package in with Composer. It auto-registers the server.
composer require builtbyberry/laravel-swarm-mcpStep 02
Connect a client
Point your MCP client at the stdio server. In Claude Desktop, that is a one-line command entry.
{
"mcpServers": {
"laravel-swarm": {
"command": "php",
"args": ["artisan", "mcp:start", "laravel-swarm"]
}
}
}
Prefer the networked transport? Enable the HTTP transport (behind Sanctum) with php artisan vendor:publish --tag=swarm-mcp-config and edit config/swarm-mcp.php. Full setup lives in the README.
Part of Swarm
A companion to the framework.
laravel-swarm-mcp reads what laravel-swarm persists. Start with the framework, add the MCP server when you want an AI client to see it work — and pair it with laravel-swarm-filament when you want a panel too.