1. Manuals
  2. Tumbleweed
  3. perl-MCP
  4. MCP::Server::Transport::HTTP(3pm)

Scroll to navigation

MCP::Server::Transport::HTTP(3) User Contributed Perl Documentation MCP::Server::Transport::HTTP(3)

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.

Only "POST" requests are handled; "GET" and "DELETE" are answered with status 405. The protocol is stateless, so nothing is remembered between requests and the transport can be deployed behind a load balancer and a pre-forking web server. Notifications that belong to a request, such as progress reports, are delivered on the response stream of that very request, which is upgraded from "application/json" to "text/event-stream" whenever there is something to deliver.

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.

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.

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

origins

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

Origins allowed to make browser requests, as an array reference of exact matches or a callback returning true for an acceptable origin. Requests carrying an "Origin" header that is not allowed are rejected with status 403, which protects against DNS rebinding attacks on servers bound to localhost. Defaults to "undef", which accepts every origin.

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

notifications

  my $bool = $http->notifications;

True when "streaming" is enabled, false otherwise.

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.

SEE ALSO

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

2026-07-31 perl v5.44.0