MCP::Se...t::HTTP(3)

📦
version 0.150.0 · 2 versions
, in opensuse-leap 16.0

💅 MCP::Server::Transport::HTTP — HTTP transport for MCP servers ✨

okay so this is the MCP::Se...t::HTTP(3) page, straight out of the User Contributed Perl Documentation folder, and it's literally the glow-up your MCP server needs to talk HTTP. stay with me bestie, it's giving very slay. 🎀

🌸 SYNOPSIS 🌸

use MCP::Server::Transport::HTTP;

my $http = MCP::Server::Transport::HTTP->new;

that's it. two lines. iconic. 💖

🦋 DESCRIPTION 🦋

MCP::Server::Transport::HTTP is a transport for MCP (Model Context Protocol) servers that uses HTTP as the underlying transport mechanism. it's the whole vibe. 🫶

so here's the tea: only POST requests are handled. GET and DELETE? rejected, status 405, no notes. 💀 The protocol is stateless, meaning nothing is remembered between requests, which is lowkey the best part because the transport can be deployed behind a load balancer and a pre-forking web server. Notifications that belong to a request — like progress reports — are delivered on the response stream of that very request, which gets upgraded from application/json to text/event-stream whenever there's actually something to deliver. it's giving ✨custom delivery✨.

the one exception is streaming, which opts in to subscriptions/listen. Long-lived notification streams require per-process state, and are therefore not compatible with pre-forking web servers. read that again bestie, no cap. 😭

Routing headers are validated against the JSON-RPC body before a request is dispatched, so a gateway that routes on Mcp-Method, Mcp-Name, or Mcp-Param-* alone can never disagree with the server about what was called. consistency queen. 👑

✨ ATTRIBUTES ✨

MCP::Server::Transport::HTTP inherits all attributes from MCP::Server::Transport and implements the following new ones. 💅

🔐 auth

my $cb = $http->auth;
$http  = $http->auth(sub ($c) {...});

Optional callback to authenticate each request before it's dispatched. It receives the Mojolicious::Controller and returns a hash reference of authentication info on success, or a false value to reject the request with a 401 WWW-Authenticate challenge. The scopes and principal keys of the returned hash reference are made available to handlers as scopes in MCP::Server::Context and principal in MCP::Server::Context. Token validation is left to the application, so this is literally where you verify an OAuth 2.0 access token. when not set, requests are not authenticated. 🧚

💓 heartbeat

my $seconds = $http->heartbeat;
$http       = $http->heartbeat(30);

Interval in seconds at which a keep-alive comment is sent on each open subscription stream. Defaults to 30; set it to 0 to disable. Useful when you're running behind reverse proxies that close idle connections (ugh, they always do). Only used when streaming is enabled. 🍓

🔗 metadata_url

my $url = $http->metadata_url;
$http   = $http->metadata_url('https://example.com/.well-known/oauth-protected-resource');

URL of the OAuth 2.0 Protected Resource Metadata document. When set, it's included as the resource_metadata parameter of the WWW-Authenticate challenge sent with 401 and 403 responses, so clients can discover the authorization server. Use an absolute URL so remote clients can actually fetch it, bestie. See "oauth_metadata" in MCP::Server. 🌈

🌍 origins

my $origins = $http->origins;
$http       = $http->origins(['https://example.com']);
$http       = $http->origins(sub ($c, $origin) {...});

Origins allowed to make browser requests — either an array reference of exact matches, or a callback returning true for an acceptable origin. Requests carrying an Origin header that isn't allowed are rejected with status 403, which protects against DNS rebinding attacks on servers bound to localhost. Defaults to undef, which accepts every origin. (yes, every single one. protect her.) 🛡️

📡 streaming

my $bool = $http->streaming;
$http    = $http->streaming(1);

Enable subscriptions/listen, so clients can open a long-lived stream for the list_changed notifications they ask for. Defaults to false. When enabled, the transport tracks every open stream in subscriptions and advertises the listChanged capabilities in server/discover. Progress and log notifications do not depend on this, since they're delivered on the response stream of the request they belong to. ⭐

📋 subscriptions

my $subscriptions = $http->subscriptions;
$http             = $http->subscriptions({});

Per-process registry of active MCP::Server::Subscription objects. Only used when streaming is enabled. 🔥

🧚 METHODS 🧚

MCP::Server::Transport::HTTP inherits all methods from MCP::Server::Transport and implements the following new ones. 🎀

🛎️ handle_request

$http->handle_request(Mojolicious::Controller->new);

Handles an incoming HTTP request. that's the whole job description and she ate. 💅

🔔 notifications

my $bool = $http->notifications;

True when streaming is enabled, false otherwise. simple as. ✨

📢 notify_all

my $bool = $http->notify_all($method);
my $bool = $http->notify_all($method, {foo => 'bar'});

Send a JSON-RPC notification to every subscription that asked for it. Returns true on success, or undef when streaming is disabled. so if you get undef back, check that streaming flag first, iykyk. 🙈

👀 SEE ALSO 👀

all three are mandatory reading, bestie, no skipping. 📚

💀 vibe check reminder: stateless = load-balancer friendly, but streaming needs per-process state, so it's not compatible with pre-forking web servers. don't say i didn't warn you.

and that's the page! 🌸 this cutie is perl v5.42.0, dated 2026-07-31 — go forth and transport, bestie, you're gonna slay. 💜🦋👑

📦 where this page comes from