PHP reference

​

Options

​

Framework and transport details

​

Official PHP MCP SDK

• track() can come before or after your tools and build(). It never throws: on failure, it logs the reason and returns the server unchanged. A second call changes nothing.
• After build(), a call to an unknown tool, a call with invalid arguments, and a call that your own tools/call handler answers give no event. A server with setReferenceHandler() stays untracked. Tracking the Builder before build() avoids both.
• Your own tools/call and tools/list handlers keep working, because AgentCat’s handlers delegate to them.

​

HTTP servers

<?php

declare(strict_types=1);

use AgentCat\AgentCat;
use Http\Discovery\Psr17Factory;
use Mcp\Server;
use Mcp\Server\Session\FileSessionStore;
use Mcp\Server\Transport\StreamableHttpTransport;

require __DIR__ . '/vendor/autoload.php';

$builder = Server::builder()
    ->setServerInfo('my-server', '1.0.0')
    ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
    ->addTool(static fn(int $a, int $b): int => $a + $b, 'add', description: 'Adds two numbers');

AgentCat::track($builder);

$factory = new Psr17Factory();
$request = $factory->createServerRequestFromGlobals();
$response = $builder->build()->run(new StreamableHttpTransport($request, $factory, $factory));

$body = (string) $response->getBody();
http_response_code($response->getStatusCode());
foreach ($response->getHeaders() as $name => $values) {
    foreach ($values as $value) {
        header($name . ': ' . $value, false);
    }
}
// Apache mod_php, php-cgi, and php -S: with the length, the client has the whole answer before AgentCat delivers.
header('Content-Length: ' . strlen($body));
echo $body;

​

Stateless endpoints

​

Custom events

​

Laravel

• A hook class resolves from the container when it runs. If it fails, AgentCat logs a line, and the tool call is not affected.
• laravel/mcp 1.x has no MCP sessions. Over HTTP, the client name comes only from the _meta of each call.
• A handler in the $methods property of your server keeps its events. A handler that you set in boot() replaces AgentCat’s handler, so that method gives no event.

​

Symfony

​

Runtimes, delivery, and shutdown

• PHP-FPM keeps the worker busy during delivery. FPM stops a worker at request_terminate_timeout, so we recommend at least 6 seconds plus your hook time over your slowest request.
• Octane keeps the events of an idle worker until its next request or until it stops. A Swoole max_wait_time below 3 seconds can cut the final delivery short.
• Signals. Without ext-pcntl (on Windows, and in the official PHP Docker images until docker-php-ext-install pcntl), events that wait at a signal are lost. Under Swoole and OpenSwoole, AgentCat installs no signal handlers.
• Async runtimes that interleave calls in one process, such as Swoole coroutines or ReactPHP, are not supported in version 1.
• Hardened hosts. Without the ext-curl functions in disable_functions, AgentCat sends nothing, and it logs each lost feature.

​

Logging and debug mode

• AgentCat setup complete | project ... | tracing=true context=true reportMissing=true exporters=0: track() worked.
• Successfully sent event ... | mcp:tools/call | session ... | <user>: an event reached AgentCat, for the user ID from identify, or anonymous.
• Shutting down with <n> events still in queue: the 5-second budget ran out.

​

Testing

<?php

declare(strict_types=1);

use AgentCat\AgentCat;
use AgentCat\Event;
use Mcp\Server;
use Mcp\Server\Transport\InMemoryTransport;
use PHPUnit\Framework\TestCase;

final class EchoToolTest extends TestCase
{
    protected function tearDown(): void
    {
        AgentCat::setClient(null); // the real client again, which stays off in tests
    }

    public function testTheEchoCallIsTracked(): void
    {
        $fake = AgentCat::fake(); // first: a server tracked before fake() is not tracked at all

        $builder = Server::builder()
            ->setServerInfo('echo-mcp', '0.1.0')
            ->addTool(static fn(string $msg): string => $msg, 'echo', description: 'Echo a message');
        AgentCat::track($builder, 'proj_YOUR_PROJECT_ID');

        $builder->build()->run(new InMemoryTransport([
            '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}',
            '{"jsonrpc":"2.0","method":"notifications/initialized"}',
            '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"echo","arguments":{"msg":"hi"}}}',
        ]));

        $fake->assertTrackedCount(1);
        $fake->assertTracked(static fn(Event $event): bool => $event->resourceName === 'echo');
    }
}

​

Differences and known limits

• Hooks run after the response, with no time limit. The TypeScript SDK runs them during the call, with a 30-second limit.
• A null project ID reads AGENTCAT_PROJECT_ID. In TypeScript, it means no project.
• Every page of tools/list is read under PHP-FPM, so your own tools/list handler runs once for each page.
• A context that is a number, boolean, or object drops the event.
• Delivery uses ext-curl and the libcurl proxy settings (HTTPS_PROXY, NO_PROXY), and follows no redirects.
• Exporters can get up to 4 copies of an event.

​

Request headers

​

Diagnostics

​

Known limits

• Sizes. AgentCat cuts each string to 32 KB, each event to 100 KB, and the intent text to 2,048 characters. Objects keep 10 levels and 100 keys or items for each level.
• Long names. The AgentCat API drops events with a name over 255 characters or a version over 50.
• Your own shutdown functions that call exit() lose the waiting events.
• Forks after the first event can send waiting events twice.
• symfony/mcp-bundle 0.15 is not in the test matrix yet, and a new install picks it. You can stay on the tested range with composer require symfony/mcp-bundle:^0.14.