NAME
MCP::Server::Transport::HTTP - HTTP transport for MCP servers
SYNOPSIS
use MCP::Server::Transport::HTTP;
my $http = MCP::Server::Transport::HTTP->new;DESCRIPTION
MCP::Server::Transport::HTTP is a transport for MCP (Model Context Protocol) server that uses HTTP as the underlying transport mechanism.
By default only POST requests are handled. When "streaming" is enabled, the transport additionally supports the server-to-client SSE stream (GET) and explicit session termination (DELETE) defined by the Streamable HTTP transport. Note that this requires per-process state and is therefore not compatible with pre-forking web servers.
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 is 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 key of the returned hash reference is made available to handlers as "scopes" in MCP::Server::Context. Token validation is left to the application, so this is 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 server-to-client stream. Defaults to 30; set to 0 to disable. Useful when running behind reverse proxies that close idle connections. 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 is 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 fetch it. See "oauth_metadata" in MCP::Server.
session_timeout
my $seconds = $http->session_timeout;
$http = $http->session_timeout(3600);Idle timeout in seconds for sessions without an open server-to-client stream. Defaults to 3600; set to 0 to disable. A periodic sweep removes sessions whose last activity is older than this value, so the effective lifetime of an idle session is up to twice the configured timeout. Only used when "streaming" is enabled.
sessions
my $sessions = $http->sessions;
$http = $http->sessions({});Per-process registry of active MCP::Server::Session objects, keyed by session ID. Only used when "streaming" is enabled.
streaming
my $bool = $http->streaming;
$http = $http->streaming(1);Enable server-to-client streaming and session lifecycle management. Defaults to false. When enabled, the transport tracks all sessions in "sessions", accepts GET requests to open a long-lived SSE stream the server can push notifications to, and accepts DELETE requests to terminate a session. Requests for unknown sessions are rejected with status 404.
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.
notifications
my $bool = $http->notifications;True when "streaming" is enabled, false otherwise.
notify
my $bool = $http->notify($session_id, $method);
my $bool = $http->notify($session_id, $method, {foo => 'bar'});Send a JSON-RPC notification to the open SSE stream of a session. Returns true on success, or undef if the session does not exist or has no open stream. Only available when "streaming" is enabled.
notify_all
my $bool = $http->notify_all($method);
my $bool = $http->notify_all($method, {foo => 'bar'});Send a JSON-RPC notification to the open SSE stream of every active session. Returns true on success, or undef when "streaming" is disabled.
SEE ALSO
MCP, https://mojolicious.org, https://modelcontextprotocol.io.