How to serve MCP tools

livery_mcp:handler/1 exposes tools, resources, and prompts to MCP clients (Claude, IDEs, agents) over the MCP Streamable HTTP transport. You need it when you want those clients to reach your tools alongside your other routes, on the same Livery service.

Mount the handler

The handler bridges Livery to the barrel_mcp protocol engine. Livery owns the wire (H1/H2/H3, router, middleware); the engine handles the MCP protocol (POST requests, GET SSE streams, DELETE session termination). Mount it at /mcp:

Mcp = livery_mcp:handler(#{session_enabled => true}),
Router = livery_router:compile([
    {<<"POST">>,   <<"/mcp">>, Mcp},
    {<<"GET">>,    <<"/mcp">>, Mcp},
    {<<"DELETE">>, <<"/mcp">>, Mcp},
    {<<"OPTIONS">>,<<"/mcp">>, Mcp}
]),
livery:start_service(#{
    https  => #{port => 8443, cert => Cert, key => Key},
    router => Router
}).

Register tools

Tools live in the shared barrel_mcp_registry. Register them with barrel_mcp's own API; livery_mcp does not wrap it:

ok = barrel_mcp:reg_tool(<<"echo">>, my_tools, echo, #{
    description  => <<"Echo a value back">>,
    input_schema => #{
        <<"type">> => <<"object">>,
        <<"properties">> => #{<<"value">> => #{<<"type">> => <<"string">>}}
    }
}).

%% my_tools:echo/1 receives the decoded arguments map.
echo(#{<<"value">> := V}) -> <<"echo: ", V/binary>>.

The barrel_mcp application starts automatically as a Livery dependency, so the registry is ready once your release boots.

Options

handler/1 accepts a map:

Key	Default	Meaning
`session_enabled`	`true`	Use `Mcp-Session-Id` sessions
`auth`	none	A `barrel_mcp` auth provider config
`allowed_origins`	`any`	`any` or a list of allowed `Origin`s
`allow_missing_origin`	`true`	Accept requests with no `Origin`
`resource_metadata`	none	OAuth protected-resource-metadata

For public deployments, set allowed_origins to your client origins to guard against DNS-rebinding.

Notes

The handler writes the response straight to the wire and returns the taken_over sentinel, so do not stack response-mutating middleware after it.
The same handler serves all three protocols; mount it once on a multi-protocol service and MCP rides H2/H3 automatically.

How to serve MCP tools

Mount the handler

Register tools

Options

Notes

See also