/ 
Net-Async-MCP-0.001
/ Net::Async::MCP

NAME

Net::Async::MCP - Async MCP (Model Context Protocol) client for IO::Async

VERSION

version 0.001

SYNOPSIS

use IO::Async::Loop;
use Net::Async::MCP;
use Future::AsyncAwait;

my $loop = IO::Async::Loop->new;

# In-process transport (Perl MCP::Server in same process)
use MCP::Server;
my $server = MCP::Server->new(name => 'MyServer');
$server->tool(
    name         => 'echo',
    description  => 'Echo text',
    input_schema => {
        type       => 'object',
        properties => { message => { type => 'string' } },
        required   => ['message'],
    },
    code => sub { return "Echo: $_[1]->{message}" },
);

my $mcp = Net::Async::MCP->new(server => $server);
$loop->add($mcp);

# Stdio transport (external MCP server subprocess)
my $mcp = Net::Async::MCP->new(
    command => ['npx', '@anthropic/mcp-server-web-search'],
);
$loop->add($mcp);

# All transports share the same async API:
async sub main {
    await $mcp->initialize;

    my $tools = await $mcp->list_tools;
    # [{name => 'echo', description => '...', inputSchema => {...}}]

    my $result = await $mcp->call_tool('echo', { message => 'Hello' });
    # {content => [{type => 'text', text => 'Echo: Hello'}], isError => \0}

    await $mcp->shutdown;
}

main()->get;

DESCRIPTION

Net::Async::MCP is an asynchronous client for the MCP (Model Context Protocol) built on IO::Async. It connects to MCP servers via pluggable transports:

All methods return Future objects and work with Future::AsyncAwait. Call "initialize" first before using any other MCP methods.

server_info

my $info = $mcp->server_info;

Returns the server info hashref from the MCP initialize response. Contains at minimum name and version keys. Only available after "initialize" has been called.

server_capabilities

my $caps = $mcp->server_capabilities;

Returns the server capabilities hashref from the MCP initialize response. Only available after "initialize" has been called.

initialize

my $result = await $mcp->initialize;

Performs the MCP initialization handshake. Must be called before any other MCP method. Sends protocol version and client info, then receives server info and capabilities.

Returns a hashref with serverInfo and capabilities keys. Also populates the "server_info" and "server_capabilities" accessors.

list_tools

my $tools = await $mcp->list_tools;

Returns an ArrayRef of tool definition hashrefs from the MCP server. Each hashref contains name, description, and inputSchema keys.

call_tool

my $result = await $mcp->call_tool($name, \%arguments);

Calls a named tool on the MCP server with the given arguments hashref. Returns a hashref with content (ArrayRef of content blocks) and isError (boolean).

list_prompts

my $prompts = await $mcp->list_prompts;

Returns an ArrayRef of prompt definition hashrefs from the MCP server.

get_prompt

my $result = await $mcp->get_prompt($name, \%arguments);

Retrieves a named prompt from the MCP server, optionally passing arguments. Returns the prompt result hashref.

list_resources

my $resources = await $mcp->list_resources;

Returns an ArrayRef of resource definition hashrefs from the MCP server.

read_resource

my $result = await $mcp->read_resource($uri);

Reads a resource by URI from the MCP server. Returns the resource content hashref.

ping

await $mcp->ping;

Sends a ping request to verify the server is alive and responsive. Returns 1 on success, fails the returned Future if the server does not respond.

shutdown

await $mcp->shutdown;

Cleanly shuts down the MCP connection. For the Stdio transport this sends SIGTERM to the subprocess and waits for it to exit. For the InProcess transport this is a no-op.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-mcp/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudss.us/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.