/ 
Claude-Agent-0.15
/ Claude::Agent::MCP::SDKBridge

NAME

Claude::Agent::MCP::SDKBridge - Answer the CLI's MCP requests for an in-process server

SYNOPSIS

my $bridge = Claude::Agent::MCP::SDKBridge->new(
    server => $sdk_server,
    loop   => $loop,
);

my $reply = $bridge->handle($jsonrpc_message)->get;

DESCRIPTION

When an Claude::Agent::MCP::Server is listed in mcp_servers, the CLI is told it is an sdk server and sends every MCP request for it back to the SDK as a mcp_message control request. Claude::Agent::Query hands the JSON-RPC message to this bridge and writes the reply back. Nothing is spawned and no socket is opened.

The bridge implements initialize (echoing the protocol version the CLI offers, and accepting repeated handshakes, which the CLI sends when it reconnects), ping, tools/list and tools/call. Notifications get no reply. An unknown method or tool is a -32601 error; a bridge failure is -32603.

ATTRIBUTES

server

The Claude::Agent::MCP::Server. Required.

loop

The IO::Async::Loop, handed to tool handlers and used for the call timeout.

tool_timeout

Seconds a tool call may take before it is answered with an error result. Overrides CLAUDE_AGENT_TOOL_TIMEOUT.

METHODS

new

Takes a flat list of name/value pairs. Unknown names are ignored.

handle

my $future = $bridge->handle(\%message);

Returns a Future that resolves to the JSON-RPC reply hashref, or to undef for a notification. A tools/call result is { content => [...], isError => true|false }; a handler result without a content array of typed blocks becomes an error result. The text of each block is sent as a string: the CLI rejects a JSON number there, which a Perl handler returning the result of arithmetic would otherwise produce.

timeout_seconds

The tool call timeout in force: tool_timeout, else the environment variable CLAUDE_AGENT_TOOL_TIMEOUT clamped to 1 to 300, else 60.

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