Urchin (Urchin v0.1.0)

Copy Markdown View Source

A Model Context Protocol (MCP) server library implementing the 2025-11-25 specification over the Streamable HTTP transport.

See Urchin.Server for authoring a server (behaviour or DSL) and Urchin.Transport.StreamableHTTP for mounting it as a Plug. The convenience runner below boots a server with a standalone Bandit endpoint.

Summary

Functions

broadcast(method, params \\ nil)

Sends a notification to every active session on its general (GET) stream.

protocol_version()

The latest protocol revision implemented by this library.

start_link(server, opts \\ [])

Starts a server module behind a standalone Bandit HTTP endpoint.

Functions

broadcast(method, params \\ nil)

@spec broadcast(String.t(), map() | nil) :: non_neg_integer()

Sends a notification to every active session on its general (GET) stream.

Useful for fan-out notifications such as notifications/tools/list_changed or notifications/resources/list_changed. Sessions without a connected GET stream buffer the notification for resumption.

Returns the number of sessions notified.

protocol_version()

@spec protocol_version() :: String.t()

The latest protocol revision implemented by this library.

start_link(server, opts \\ [])

@spec start_link(
  module(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Starts a server module behind a standalone Bandit HTTP endpoint.

Requires the optional :bandit dependency. Options are forwarded to Urchin.Endpoint.start_link/1; common ones are :port, :path, :ip and transport options such as :allowed_origins.

Example

{:ok, _pid} = Urchin.start_link(MyServer, port: 4000, path: "/mcp")