PHP: Laravel

​

Requirements

• PHP 8.3, 8.4 or 8.5.
• laravel/mcp 1.x, with Laravel 12.41.1 or later, or Laravel 13. On every pull request and every night, CI tests AgentCat with the newest patch of each laravel/mcp minor release from 1.0 up.
• ext-curl, to send the events.

​

Install

composer require agentcat/sdk
php artisan agentcat:install

• It checks the ID: proj_ followed by 27 letters or digits.
• It writes AGENTCAT_PROJECT_ID into .env. When the application has no .env file, it creates one with that key only, and says so.
• It adds an empty AGENTCAT_PROJECT_ID= to .env.example, when the application has one.
• With --config, it also publishes config/agentcat.php.
• It sends nothing over the network.

​

What AgentCat tracks

• Every laravel/mcp server that the container resolves, also when laravel/mcp builds the server for each HTTP request. The server of Laravel Boost is excluded by default.
• Every tool call. AgentCat adds a session_id and a context parameter to the input schema of each tool (and agent_id with enable_agent_tracking), and removes them from the arguments before your tool runs. It adds the get_more_tools tool.
• After the response. AgentCat runs your hooks and sends the events in Laravel’s terminating() callbacks, after the client has its answer.

​

Configuration reference

php artisan vendor:publish --tag=agentcat-config

​

exclude and projects

• null, or no exclude key, is the default list: Laravel Boost’s server.
• [] excludes nothing, Laravel Boost’s server included.
• A blank string names no server: AgentCat logs one warning and uses the default list.

return [
    // ...
    'exclude' => [
        'Laravel\Boost\Mcp\Boost',
        App\Mcp\Servers\InternalServer::class,
    ],

    'projects' => [
        App\Mcp\Servers\BillingServer::class => env('AGENTCAT_BILLING_PROJECT_ID'),
    ],
];

​

The log file

​

Hooks are invokable classes

namespace App\AgentCat;

use AgentCat\Identity;
use AgentCat\ToolCall;

final class IdentifyActor
{
    public function __invoke(ToolCall $call): ?Identity
    {
        $token = $call->headers['authorization'] ?? null;

        return $token === null ? null : new Identity(userId: hash('sha256', $token));
    }
}

// config/agentcat.php
return [
    // ...
    'identify' => App\AgentCat\IdentifyActor::class,
];

​

Exporters

return [
    // ...
    'exporters' => [
        'otlp' => ['type' => 'otlp', 'endpoint' => 'http://localhost:4318/v1/traces'],
        'datadog' => [
            'type' => 'datadog',
            'apiKey' => env('DD_API_KEY'),
            'site' => 'datadoghq.com',
            'service' => 'my-mcp-server',
        ],
        'sentry' => null, // a null entry is skipped
    ],
];

​

Octane and other long-running workers

• The wait shows in request durations. The worker’s time for a request that sends events can be up to 1 second longer, in Octane’s numbers and in your monitoring. The client has its answer before the wait.
• An idle worker holds its last request’s events. Events that are still waiting after the 1 second go out at the next request of the worker, or when the worker stops.
• When a worker stops, AgentCat delivers what is left for at most 5 seconds, at Octane’s WorkerStopping event. Measured on Swoole 6.2.3: when the whole server stops, Swoole did not cut that delivery. A worker that Swoole restarts (for example after Octane’s --max-requests) is stopped by force about twice its max_wait_time server setting after it is told to stop: about 6 seconds with the default of 3. So a max_wait_time below 3 seconds can cut the delivery of a restarting worker short, and with the default, the other WorkerStopping listeners leave AgentCat its 5 seconds only when they take less than about 1 second.

​

Your own method handlers

namespace App\Mcp\Servers;

use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Methods\CallTool;

class AuditedCallTool extends CallTool
{
    // Your own tools/call handling.
}

final class BillingServer extends Server
{
    protected function boot(): void
    {
        // AgentCat never sees this handler: no event for any tools/call of this server.
        $this->addMethod('tools/call', AuditedCallTool::class);
    }
}

​

ToolSearch catalogs

​

Streamed answers

​

Client name and version

​

Responses on Apache mod_php, php-cgi and php -S

​

Testing

namespace Tests\Feature;

use AgentCat\AgentCat;
use AgentCat\Event;
use App\Mcp\Servers\WeatherServer;
use App\Mcp\Tools\CurrentWeatherTool;
use Tests\TestCase;

final class WeatherToolTest extends TestCase
{
    protected function tearDown(): void
    {
        AgentCat::setClient(null);
        parent::tearDown();
    }

    public function test_the_weather_tool_call_is_tracked(): void
    {
        $fake = AgentCat::fake();

        WeatherServer::tool(CurrentWeatherTool::class, ['location' => 'Paris'])->assertHasNoErrors();

        $fake->assertTrackedCount(1);
        $fake->assertTracked(fn (Event $event): bool => $event->isError !== true);
    }
}

• Two settings outlive the test that made them. The fake stays the shared client of the PHP process until AgentCat::setClient(null). The agentcat.enabled value that the service provider reads when the application boots stays in effect until the next application boots.
• With the fake, AgentCat changes the answers as in production. A call without a session_id gets the issued session ID as the first text block of content. A tool with an output schema gets an mcp_session entry in its structuredContent. An assertion on the exact structuredContent (for example assertStructuredContent()) then sees that entry.
• A bad value in config/agentcat.php logs one line per test application, also without the fake, because each test boots a new application. The lines go to storage/logs/agentcat.log.

​

Laravel Boost guidelines