Add Logging Support

[pushpak1300]

This PR adds support for the MCP logging utility, allowing servers to send structured log messages to clients.

Logging is opt in. MCP servers will not enable this by default. To turn it on, the user must explicitly add the capability in their MCP server class:

protected function boot(): void
{
    $this->addCapability(self::CAPABILITY_LOGGING);
}

Once enabled, client can send logging/setLevel request. User can log things but filtering won't happen without this capability.

How It Works

1. Default level: Info (Debug is filtered out unless enabled)
2. Client control: Clients call logging/setLevel to adjust verbosity
3. Automatic filtering: Server only emits logs at or above the current threshold
4. Session isolation: Each connection maintains its own log level
5. Cache-backed state: Session data is stored via Laravel cache, which works for both STDIO and HTTP transports (unlike Laravel sessions)

Usage

Basic Logging

use Laravel\Mcp\Enums\LogLevel;

class DatabaseTool extends Tool
{
    public function handle(Request $request): Generator
    {
        yield Response::log(LogLevel::INFO, 'Connecting to database');

        try {
            $result = DB::query(...);
            yield Response::log(LogLevel::DEBUG, ['query' => $sql, 'rows' => $result->count()]);
            yield Response::text("Found {$result->count()} records");
        } catch (\Exception $e) {
            yield Response::log(LogLevel::ERROR, ['error' => $e->getMessage()], 'database');
            yield Response::error('Query failed');
        }
    }
}

Testing

MyServer::tool(DatabaseTool::class)
    ->assertLogSent(LogLevel::INFO, 'Connecting')
    ->assertLogSent(LogLevel::ERROR)
    ->assertLogCount(2);

Configuration

// config/mcp.php
'session_ttl' => env('MCP_SESSION_TTL', 86400), // 24 hours

[joetannenbaum]

This looks good overall, just the one nit comment about the cases as opposed to hardcoding, I'll let you make the call there.

Is this the first time we're doing something like $this->addCapability('logging'); as a public facing user API? Is that string essentially arbitrary or are there pre-defined use cases? Either way, for built-in capabilities, do we want to avoid the magic string and provide a helper method such as enableLogging or something similar?

[pushpak1300]

Is this the first time we're doing something like $this->addCapability('logging'); as a public facing user API? Is that string essentially arbitrary or are there pre-defined use cases? Either way, for built-in capabilities, do we want to avoid the magic string and provide a helper method such as enableLogging or something similar?

Yes, this is the first time we’re exposing $this->addCapability('logging') in the public API. The string is predefined, it comes directly from the MCP spec. I agree we should avoid raw strings. Adding a constant makes sense, but I don’t think a helper like enableLogging is necessary since the capability API already exists.

And keeping this opt-in feels right, since most MCP users won’t need logging unless they know exactly what they’re doing.

[taylorotwell]

Kinda want to wait for more demand for this since it's a beefy PR to maintain.

[joetannenbaum]

Ok, well, just reviewed this not realizing it was a draft 🤦

Regardless, if we decide to ever go with this please refer to my comments.

[joetannenbaum]

A whole SessionStore setup seems a bit overblown for this, we're not even using all of the methods. Are we planning on utilizing this in the future for something specific? If not, let's just have the logging manager class interact directly with the cache, right?

[pushpak1300]

Yeah that can be done.

[joetannenbaum]

If these are never set after the contructor, any reason to not make them just public readonly properties? Instead of getter methods?