Getting Started

View Source

This guide will help you get started with barrel_mcp, an Erlang library implementing the Model Context Protocol (MCP) specification.

Installation

Add barrel_mcp to your rebar.config dependencies:

{deps, [
    {barrel_mcp, "1.0.0"}
]}.

Or from git:

{deps, [
    {barrel_mcp, {git, "https://github.com/barrel-db/barrel_mcp.git", {tag, "v1.0.0"}}}
]}.

Starting the Application

%% Start the barrel_mcp application
application:ensure_all_started(barrel_mcp).

%% Wait for registry to be ready (recommended)
ok = barrel_mcp_registry:wait_for_ready().

Your First MCP Server

1. Register a Tool

Tools are functions that can be called by MCP clients (like Claude):

-module(my_tools).
-export([greet/1]).

%% Arity-1 handler — gets only the call arguments. The simplest
%% shape; pick this when you don't need progress, cancellation, or
%% session context. For arity-2 handlers (with a Ctx parameter),
%% see the Tools guide.
greet(Args) ->
    Name = maps:get(<<"name">>, Args, <<"World">>),
    <<"Hello, ", Name/binary, "!">>.

Register it:

barrel_mcp:reg_tool(<<"greet">>, my_tools, greet, #{
    description => <<"Greet someone by name">>,
    input_schema => #{
        <<"type">> => <<"object">>,
        <<"properties">> => #{
            <<"name">> => #{
                <<"type">> => <<"string">>,
                <<"description">> => <<"Name to greet">>
            }
        }
    }
}).

2. Start the HTTP Server

{ok, _} = barrel_mcp:start_http_stream(#{port => 9090}).

The Streamable HTTP server binds to 127.0.0.1 by default and validates the Origin header on every request. Public binds (any non-loopback IP) require an explicit allowed_origins — see the Streamable HTTP guide for the security defaults.

The legacy plain-HTTP transport (start_http/1, JSON-RPC only, protocol 2024-11-05) is still available for clients that don't speak the Streamable HTTP transport.

3. Test Your Server

Using curl:

# Initialize
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# List tools
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call your tool
curl -X POST http://localhost:9090/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"greet","arguments":{"name":"Erlang"}}}'

Using with Claude Desktop

For Claude Desktop integration, use the stdio transport:

  1. Create an escript or release that calls barrel_mcp:start_stdio()
  2. Configure Claude Desktop's claude_desktop_config.json:
{
  "mcpServers": {
    "my-server": {
      "command": "/path/to/my_app",
      "args": ["mcp"]
    }
  }
}

Next Steps