/ 
Claude-Agent-0.08
/ 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 by default.

============================================================================

SECURITY WARNING FOR PRODUCTION/MULTI-TENANT ENVIRONMENTS

============================================================================

In high-security or multi-tenant environments, symlinks within allowed directories (e.g., /Users/attacker/perl5/) could be exploited to inject malicious Perl libraries.

REQUIRED for production/multi-tenant: Set one of the following:

# Option 1: Enable strict symlink checking (RECOMMENDED):
$ENV{CLAUDE_AGENT_PERL5LIB_STRICT} = 1;

# Option 2: Set PERL5LIB explicitly to trusted paths only:
$ENV{PERL5LIB} = '/path/to/trusted/lib:/path/to/other/lib';

Setting CLAUDE_AGENT_PERL5LIB_STRICT=1 causes the module to reject any library paths that are symlinks, preventing potential library injection attacks. This is the recommended approach for any environment where untrusted users may have write access to directories within the allowed path prefixes.

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).