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.

Changes in v0.4.0

The server is now fully 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