# 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](https://modelcontextprotocol.io/specification/2025-11-25).  
The implementation is checked in CI by the official MCP conformance tool
and the official TypeScript SDK client.  
_(See [CONFORMANCE.md](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

  * **Server features**: tools, resources, resource templates, prompts
    and completions, with resource subscriptions and paginated lists.
  * **Tools**: input and output JSON Schemas compiled at boot, input
    checked before the callback runs, `structuredContent` checked
    against the output schema, annotations and icons.
  * **Utilities**: log messages with the level of the client, progress
    notifications, request cancellation and ping.
  * **Requests to the client**: sampling with tools, elicitation in the
    form and the URL modes and roots, sent from any callback.
  * **Tasks in both directions** (experimental, off by default): a
    `tools/call` that answers at once with a task, for a tool that sets
    `task_support` and requests that run as tasks of the client, with
    the runtime option `client_tasks: true`.
  * **Two transports, the same answers**: Streamable HTTP with SSE
    streams and resume through `Last-Event-ID` and stdio through
    `mix oz_mcp.stdio`.
  * **Authorization**: an OAuth 2.1 resource server, with the Protected
    Resource Metadata document, sessions bound to their principal,
    scopes for each entity, lists filtered by scope and the end of the
    sessions of a principal.

### Declare, do not wire

  * **A DSL or plain data**: declare each entity with a DSL checked at
    compile time, or return structs and maps from `list/0`.
  * **Capabilities from the declarations**: the server announces what
    its modules declare.
  * **A guard around user code**: a raise in a callback gives the error
    `-32603` to the client, never a lost request.
  * **Many servers in one application**, each on its own path.

### Built for production

  * **More than 40 runtime options** for each server: timeouts, limits,
    SSE streams, tasks, checks of the results, sessions and
    authorization, readable from the environment of a release.
  * **Limits** on sessions, sessions of a principal, streams,
    subscriptions, the log rate, tasks, the request body and the token
    size.
  * **Browser safety**: an allow list of the browser origins (the boot
    refuses `"*"`) and an allow list of the hosts against DNS
    rebinding.
  * **Telemetry**: spans for the requests, the callbacks, the sessions,
    the tasks and the requests to the client and events for the auth
    refusals, the limits and the snapshots.
  * **Many nodes**: broadcasts across the cluster through `:pg`
    (`OzMcp.PubSub.PG`), a guide for sticky routing on `Mcp-Session-Id`
    and failover of the sessions through a snapshot store.
  * **Bandit or Cowboy** as the HTTP server.
  * **Conformance measured in CI** by the official MCP conformance tool
    and the official TypeScript SDK client.
  * **Testing helpers** (`OzMcp.Testing`) to test a server, its tools,
    resources, templates and prompts.

## What OzMcp does not do

  * **No list changes at run time**: the server reads its modules at
    boot and never announces `listChanged`. A change of a module needs
    a restart of the instance.
  * **One revision of the protocol**: `2025-11-25` only.
  * **Tasks can change**: the tasks are experimental in the protocol
    and they can change or go away before 1.0.

## Installation

OzMcp needs Elixir `~> 1.19`.

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

```elixir
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:

```elixir
{: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:

```elixir
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:

```elixir
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.

```elixir
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:

```elixir
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`:

```shell
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:

```shell
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](https://hexdocs.pm/oz_mcp).

  * [Getting started](guides/introduction/getting_started.md): from an
    empty Mix project to the first `tools/list` response.
  * [Declare a server](guides/servers/declare_a_server.md): the blocks
    of a server module and the automatic capabilities.
  * [Entity modules](guides/entities/overview.md): the rules that the
    four kinds of entity share.
  * Each kind of entity: [Tools](guides/entities/tools.md),
    [Resources](guides/entities/resources.md),
    [Templates](guides/entities/templates.md),
    [Prompts](guides/entities/prompts.md) and
    [Completions](guides/entities/completions.md).
  * [Runtime options](guides/runtime/runtime_options.md): each option
    of a server and the configuration of a release.
  * [HTTP transport](guides/runtime/http_transport.md): the mount, the
    streams and the resume, the limits and Cowboy.
  * [stdio transport](guides/runtime/stdio_transport.md): the Mix task
    and the client configuration.
  * [Authorization](guides/runtime/authorization.md): the verifier, the
    metadata document and the scopes.
  * [Tasks](guides/runtime/tasks.md): a `tools/call` that runs in the
    background.
  * [Run many nodes](guides/runtime/cluster.md): broadcasts, sticky
    routing, failover and the rolling deploy.
  * [Requests to the client](guides/runtime/client_requests.md):
    sampling, elicitation and roots.
  * [Notifications](guides/runtime/notifications.md): logs, progress
    and the broadcasts.
  * [Telemetry](guides/runtime/telemetry.md): the events and their
    metadata.
  * [Testing](guides/development/testing.md): test the tools, prompts
    and resources of a server with `OzMcp.Testing`.
  * Long examples: [Tool examples](guides/long_examples/tool_examples.md),
    [Resource examples](guides/long_examples/resource_examples.md),
    [Template examples](guides/long_examples/template_examples.md),
    [Prompt examples](guides/long_examples/prompt_examples.md).

## Contributing

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

## License

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

## Authors

Designed and initially written by hand by [@odelbos](https://github.com/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. |