/ 
Claude-Agent-0.03
/ Claude::Agent::MCP

NAME

Claude::Agent::MCP - MCP (Model Context Protocol) server integration

SYNOPSIS

use Claude::Agent qw(query tool create_sdk_mcp_server);
use Claude::Agent::Options;

# Create custom tools that execute locally
my $calculator = tool(
    'calculate',
    'Perform basic arithmetic calculations',
    {
        type       => 'object',
        properties => {
            a => {
                type        => 'number',
                description => 'First operand',
            },
            b => {
                type        => 'number',
                description => 'Second operand',
            },
            operation => {
                type        => 'string',
                enum        => ['add', 'subtract', 'multiply', 'divide'],
                description => 'The arithmetic operation to perform',
            },
        },
        required => ['a', 'b', 'operation'],
    },
    sub {
        my ($args) = @_;
        my ($a, $b, $op) = @{$args}{qw(a b operation)};

        my $result = $op eq 'add'      ? $a + $b
                   : $op eq 'subtract' ? $a - $b
                   : $op eq 'multiply' ? $a * $b
                   : $op eq 'divide'   ? ($b != 0 ? $a / $b : 'Error: division by zero')
                   :                     'Error: unknown operation';

        return {
            content => [{ type => 'text', text => "Result: $result" }]
        };
    }
);

my $lookup = tool(
    'lookup_user',
    'Look up user information by ID',
    {
        type       => 'object',
        properties => {
            user_id => {
                type        => 'integer',
                description => 'User ID to look up',
            },
        },
        required => ['user_id'],
    },
    sub {
        my ($args) = @_;
        # In real code, this would query a database
        my %users = (1 => 'Alice', 2 => 'Bob', 3 => 'Charlie');
        my $name = $users{$args->{user_id}} // 'Unknown';
        return {
            content => [{ type => 'text', text => "User: $name" }]
        };
    }
);

# Create an SDK MCP server with the tools
my $server = create_sdk_mcp_server(
    name    => 'math',
    tools   => [$calculator, $lookup],
    version => '1.0.0',
);

# Use the tools in a query
my $options = Claude::Agent::Options->new(
    mcp_servers     => { math => $server },
    allowed_tools   => ['mcp__math__calculate', 'mcp__math__lookup_user'],
    permission_mode => 'bypassPermissions',
);

my $iter = query(
    prompt  => 'Calculate 15 multiplied by 7, then look up user 1',
    options => $options,
);

while (my $msg = $iter->next) {
    # Tool handlers execute locally when Claude calls them
    if ($msg->isa('Claude::Agent::Message::Result')) {
        print $msg->result, "\n";
        last;
    }
}

DESCRIPTION

This module provides MCP (Model Context Protocol) server integration for the Claude Agent SDK, allowing you to create custom tools that Claude can use.

SDK MCP tools execute locally in your Perl process. When Claude calls a tool, the SDK intercepts the request, runs your handler, and returns the result. This allows your tools to access databases, APIs, application state, and other resources available to your Perl application.

MCP SERVER TYPES

  • sdk - In-process server running within your application

  • stdio - External process communicating via stdin/stdout

  • sse - Remote server using Server-Sent Events

  • http - Remote server using HTTP

MCP CLASSES

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