Behaviour for implementing stateless MCP servers.

An MCP server provides tools, resources, and prompts to LLM clients. Servers implement callbacks to handle client requests concurrently.

Architecture

Server modules are stateless — just pure compiled functions:

• No GenServer, no Agent, no process overhead
• No supervision tree required
• Callbacks receive the Plug.Conn for request context
• Each HTTP request runs in parallel (limited only by Bandit's process pool)

Example (Using DSL - Recommended)

defmodule MyApp.MCPServer do
  use ConduitMcp.Server

  tool "echo", "Echo back the input" do
    param :message, :string, "Message to echo", required: true

    handle fn _conn, %{"message" => msg} ->
      text(msg)
    end
  end

  tool "calculate", "Perform calculations" do
    param :operation, :string, "Math operation", enum: ~w(add sub mul div), required: true
    param :a, :number, "First number", required: true
    param :b, :number, "Second number", required: true

    handle MyMath, :calculate
  end
end

Example (Manual - Advanced)

defmodule MyApp.MCPServer do
  use ConduitMcp.Server, dsl: false  # Disable DSL

  @tools [
    %{
      "name" => "echo",
      "description" => "Echo back the input",
      "inputSchema" => %{
        "type" => "object",
        "properties" => %{
          "message" => %{"type" => "string", "description" => "Message to echo"}
        },
        "required" => ["message"]
      }
    }
  ]

  @impl true
  def handle_list_tools(_conn) do
    {:ok, %{"tools" => @tools}}
  end

  @impl true
  def handle_call_tool(_conn, "echo", %{"message" => msg}) do
    {:ok, %{"content" => [%{"type" => "text", "text" => msg}]}}
  end
end

Then in your supervision tree, just pass the module:

{Bandit,
 plug: {ConduitMcp.Transport.StreamableHTTP, server_module: MyApp.MCPServer},
 port: 4001}

Using Connection Context

The conn parameter allows access to request metadata:

def handle_call_tool(conn, "private_data", _params) do
  # Check authentication
  user_id = conn.assigns[:user_id]

  # Access headers
  auth_header = Plug.Conn.get_req_header(conn, "authorization")

  {:ok, %{"content" => [%{"type" => "text", "text" => "Data for #{user_id}"}]}}
end

Mutable State

If you need mutable state, use external mechanisms:

# Option 1: ETS
def handle_call_tool(_conn, "increment", _params) do
  :ets.update_counter(:my_counter, :count, 1)
  count = :ets.lookup_element(:my_counter, :count, 2)
  {:ok, %{"content" => [%{"type" => "text", "text" => "Count: #{count}"}]}}
end

# Option 2: Agent/GenServer
def handle_call_tool(_conn, "get_cache", %{"key" => key}) do
  value = MyApp.Cache.get(key)
  {:ok, %{"content" => [%{"type" => "text", "text" => value}]}}
end