/ 
Claude-Agent-0.07
/ Claude::Agent::MCP::SDKServer

NAME

Claude::Agent::MCP::SDKServer - Socket-based MCP server for SDK tools

DESCRIPTION

This module manages the IPC between the Perl SDK and the MCP server runner. It creates a Unix socket, spawns the runner as a stdio MCP server, and handles tool call requests from the runner by executing the local handlers.

SYNOPSIS

use Claude::Agent::MCP::SDKServer;

my $sdk_server = Claude::Agent::MCP::SDKServer->new(
    server => $mcp_server,  # Claude::Agent::MCP::Server object
    loop   => $loop,        # IO::Async::Loop
);

# Get the stdio config for the CLI
my $stdio_config = $sdk_server->to_stdio_config();

# Start listening for tool calls
$sdk_server->start();

socket_path

Returns the path to the Unix socket.

to_stdio_config

Returns a hashref suitable for use as a stdio MCP server config.

Security Note: The PERL5LIB environment variable is automatically filtered from @INC paths to include only known safe Perl library directories. However, symlinks within permitted directory prefixes are allowed. In high-security or multi-tenant environments where attackers could create symlinks within allowed directories (e.g., /Users/attacker/perl5/), set PERL5LIB explicitly rather than relying on automatic @INC filtering.

RECOMMENDATION for high-security environments:

# Instead of relying on automatic @INC filtering:
$ENV{PERL5LIB} = '/path/to/trusted/lib:/path/to/other/lib';

This explicit approach avoids potential symlink-based attacks within permitted directory prefixes that could be exploited in multi-tenant environments.

start

Start listening on the Unix socket for tool call requests.

Concurrent Request Handling: When multiple connections send requests concurrently, responses may be interleaved and delivered in any order. Clients MUST correlate responses using the id field from each response, which matches the id from the corresponding request. Do not assume responses arrive in request order.

stop

Stop the listener and clean up.

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).