OzMcp

OzMcp is an Elixir framework to write MCP servers. It provides a rich DSL to declare servers, tools, resources and prompts in plain modules. Currently the framework supports only the full MCP specification, revision 2025-11-25.
The implementation is checked in CI by the official MCP conformance tool and the official TypeScript SDK client.
(See CONFORMANCE.md for an overview of what is implemented, feature by feature.)

The current version is 0.9.0 (the API can change before version 1.0).

Features

The protocol

Declare, do not wire

Built for production

What OzMcp does not do

Installation

OzMcp needs Elixir ~> 1.19.

Add oz_mcp and an HTTP server to the dependencies of your application:

def deps do
  [
    {:oz_mcp, "~> 0.9.0"},
    {:bandit, "~> 1.13"}
  ]
end

Then run mix deps.get.

To follow the development version, use the git repository instead:

{:oz_mcp, github: "oz-elixir/oz_mcp", branch: "main"}

Bandit is the HTTP server of the examples. Cowboy, through plug_cowboy, is supported too: the HTTP transport guide gives its mount options.

Quick start

Write a tool module:

defmodule MyApp.Tools.EchoTool do
  use OzMcp.Config.Tool

  tool "echo" do
    title "Echo"
    description "Send back the text"

    input_schema %{
      type: "object",
      properties: %{text: %{type: "string"}},
      required: ["text"]
    }
  end

  @impl true
  def call(_ctx, %{"name" => "echo", "arguments" => %{"text" => text}}) do
    {:ok, %{content: [%{type: "text", text: text}]}}
  end
end

Write a server module that declares the tool:

defmodule MyApp.McpServer do
  use OzMcp.Config.Server

  server_info do
    name "my-app"
    version "1.0.0"
  end

  tools do
    tool MyApp.Tools.EchoTool
  end
end

Start the server and the HTTP server in the application supervisor. Put OzMcp before Bandit in the list of the children. A request that arrives before the server starts gets 503. The list allowed_origins names the origins of the browsers that can call the server. The boot refuses "*". The list allowed_hosts names the hosts that the server accepts in the Host header: it stops the DNS rebinding attacks on a local server.

children = [
  {OzMcp,
   server: MyApp.McpServer,
   allowed_origins: ["http://localhost:4000"],
   allowed_hosts: ["localhost", "127.0.0.1"]},
  {Bandit, plug: MyApp.Router, ip: {127, 0, 0, 1}, port: 4000}
]

Mount the server in your plug router:

defmodule MyApp.Router do
  use Plug.Router

  plug :match
  plug :dispatch

  forward "/mcp", to: OzMcp.Router, init_opts: [instance: MyApp.McpServer]

  match _ do
    send_resp(conn, 404, "not found")
  end
end

Send an initialize request with curl:

curl -i http://localhost:4000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-11-25","capabilities":{},
        "clientInfo":{"name":"curl","version":"1.0"}}}'

The response has an mcp-session-id header. Send this header with each next request. Send notifications/initialized before the first tools/list.

Run on stdio

For a local client, run the server on stdin and stdout:

mix oz_mcp.stdio MyApp.McpServer

stdout carries the JSON-RPC messages only. The logs and the messages of Mix go to stderr. Give --start-app to start the host application before the server starts. See Mix.Tasks.OzMcp.Stdio for the options and for the client configuration.

Guides

The guides go from an empty Mix project to a server that runs and they give each option of the entities and of the runtime. Read them on HexDocs.

Contributing

The commands of the checks, the rules of the tests and the conformance tool are in CONTRIBUTING.md.

License

OzMcp is released under the MIT License, see LICENSE. To report a security problem, see SECURITY.md.

Authors

Designed and initially written by hand by @odelbos, who remains the maintainer.

Later work was done in collaboration with AI models under the maintainer's supervision.

Model (reasoning effort) Role
Claude Opus 5.5 (high / medium) Codebase reviews, plans, tasks and implementation reviews.
Claude Sonnet 5.5 (high / medium) Plans and implementation of complex tasks.
DeepSeek V4.1 Flash (high) Implementation of complex and medium tasks.
GLM 5.3 Flash (high) Implementation of medium and simple tasks.