/ 
Claude-Agent-0.13
/ 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. Symlinks within permitted directory prefixes are rejected by default for security.

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

SECURITY WARNING FOR PRODUCTION/MULTI-TENANT ENVIRONMENTS

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

Symlinks within allowed directories (e.g., /Users/attacker/perl5/) could be exploited to inject malicious Perl libraries. For this reason, symlinks are rejected by default.

Symlink handling options:

# Symlinks are REJECTED by default (secure)

# To allow symlinks (NOT recommended for production):
$ENV{CLAUDE_AGENT_PERL5LIB_ALLOW_SYMLINKS} = 1;

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

The default behavior rejects any library paths that are symlinks, preventing potential library injection attacks. Only set CLAUDE_AGENT_PERL5LIB_ALLOW_SYMLINKS=1 if you have verified that all symlinks in your PERL5LIB paths are trusted.

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