/ 
MCP-0.15
/ MCP::Client

NAME

MCP::Client - MCP client

SYNOPSIS

use MCP::Client;

my $client = MCP::Client->new(url => 'http://localhost:3000/mcp');
my $tools  = $client->list_tools;

DESCRIPTION

MCP::Client is a client for MCP (Model Context Protocol) that communicates with MCP servers over HTTP.

It is exactly conformant on the wire, sending the _meta fields and routing headers every request has to carry, and it is deliberately nothing more than that. TTL caching, retry loops for input requests, and the OAuth authorization flow are all left to the application, so this is a good client to test a server with and a starting point rather than a finished agent.

EVENTS

MCP::Client inherits all events from Mojo::EventEmitter and emits the following new ones.

notification

$client->on(notification => sub ($client, $notification) { ... });

Emitted for every JSON-RPC notification the server sends on the response stream of a request, such as a progress report for a long running tool call.

ATTRIBUTES

MCP::Client inherits all attributes from Mojo::EventEmitter and implements the following new ones.

capabilities

my $capabilities = $client->capabilities;
$client          = $client->capabilities({elicitation => {}});

Capabilities to declare with every request, defaults to an empty hash reference.

headers

my $headers = $client->headers;
$client     = $client->headers({Authorization => 'Bearer abc123'});

Extra HTTP headers to send with every request, as a hash reference. Useful for passing an Authorization header to an MCP server that requires OAuth bearer authentication. Defaults to an empty hash reference.

name

my $name = $client->name;
$client  = $client->name('PerlClient');

The name of the client, defaults to PerlClient.

protocol_version

my $version = $client->protocol_version;
$client     = $client->protocol_version('2026-07-28');

The protocol version to make requests with, defaults to "PROTOCOL_VERSION" in MCP::Constants. A server rejecting it with an UnsupportedProtocolVersionError gets one more chance with the newest version both sides support, and that version is remembered for subsequent requests.

ua

my $ua  = $client->ua;
$client = $client->ua(Mojo::UserAgent->new);

The user agent used for making HTTP requests, defaults to a new instance of Mojo::UserAgent.

url

my $url  = $client->url;
$client  = $client->url('http://localhost:3000/mcp');

The URL of the MCP server, defaults to http://localhost:3000/mcp.

version

my $version = $client->version;
$client     = $client->version('1.0.0');

The version of the client, defaults to 1.0.0.

METHODS

MCP::Client inherits all methods from Mojo::EventEmitter and implements the following new ones.

build_notification

my $notification = $client->build_notification('method_name', {param1 => 'value1'});

Builds a JSON-RPC notification with the given method name and parameters.

build_request

my $request = $client->build_request('method_name', {param1 => 'value1'});

Builds a JSON-RPC request with the given method name and parameters, adding the _meta fields every request has to carry.

call_tool

my $result = $client->call_tool('tool_name');
my $result = $client->call_tool('tool_name', {arg1 => 'value1'});
my $result = $client->call_tool('tool_name', {arg1 => 'value1'}, {request_state => $state});

Calls a tool on the MCP server with the specified name and arguments, returning the result.

A result with resultType set to input_required is returned as-is; gathering the requested input and deciding whether to call again is up to you.

These options are currently available:

input_responses
input_responses => {confirm => {action => 'accept', content => {ok => \1}}}

Responses to the input requests of an earlier input_required result, keyed by the same names.

request_state
request_state => 'eyJ...'

The requestState of an earlier input_required result, passed back verbatim.

discover

my $result = $client->discover;

Discover the protocol versions, capabilities, and instructions of the MCP server.

get_prompt

my $result = $client->get_prompt('prompt_name');
my $result = $client->get_prompt('prompt_name', {arg1 => 'value1'});
my $result = $client->get_prompt('prompt_name', {arg1 => 'value1'}, {request_state => $state});

Get a prompt from the MCP server with the specified name and arguments, returning the result. Takes the same options as "call_tool".

list_prompts

my $prompts = $client->list_prompts;

Lists all available prompts on the MCP server.

list_resources

my $resources = $client->list_resources;

Lists all available resources on the MCP server.

list_tools

my $tools = $client->list_tools;

Lists all available tools on the MCP server.

listen

my $bool = $client->listen({toolsListChanged => \1}, sub ($message) {...});

Open a subscriptions/listen stream for the requested notification types and block, invoking the callback for every message the server sends, starting with the acknowledgement. Returning a false value from the callback closes the stream. Only servers configured with streaming => 1 support this.

read_resource

my $result = $client->read_resource('file:///path/to/resource.txt');
my $result = $client->read_resource('file:///path/to/resource.txt', {request_state => $state});

Reads a resource from the MCP server with the specified URI, returning the result. Takes the same options as "call_tool".

send_request

my $response = $client->send_request($request);

Sends a JSON-RPC request to the MCP server and returns the response, or undef if the server accepted it without one.

SEE ALSO

MCP, https://mojolicious.org, https://modelcontextprotocol.io.