# `OzMcp.Config.Server`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/config/server.ex#L1)

Behaviour of a server module. A server module declares one MCP
server: its information, its capabilities and the modules of its
tools, resources, templates and prompts.

    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

`use OzMcp.Config.Server` includes `OzMcp.Config.Server.DSL`. The
blocks of the DSL check the declaration at compile time and the
macros generate the functions of this behaviour:

  * `config/0`: the configuration of the server.
  * `initialize_result/0`: the `t:OzMcp.Structs.InitializeResult.t/0`
    of the server.
  * `authorization/0`: the map of the `authorization` block, or
    `nil`.
  * For each kind (`tools`, `resources`, `templates`, `prompts`):
    `paginate_<kind>/0`. For example `paginate_tools/0`.
  * `list_<kind>_result_meta/0` and `list_<kind>_result_extras/0`
    for the `list_result` block of each registry block.

The application does not implement the callbacks of the lists. The
DSL generates them and it checks that the key of each entity (the
name of a tool or of a prompt, the uri of a resource, the
`uri_template` of a template) is unique in the server. The optional
callback `roots_list_changed/1` has a default: override it to react
to a change of the roots of the client.

The guide *Declare a server* describes each block of the DSL.

# `name`

```elixir
@type name() :: String.t()
```

# `uri`

```elixir
@type uri() :: String.t()
```

# `uri_template`

```elixir
@type uri_template() :: String.t()
```

# `authorization`
*optional* 

```elixir
@callback authorization() :: map() | nil
```

The static authorization configuration of the server, or `nil` when the
server module declares no `authorization` block. The map holds the keys
declared in the block: `verifier`, `authorization_servers`,
`scopes_supported`, `challenge_scopes`, `filter_by_scope`,
`audience_check`, `resource_name` and `resource_documentation`.
`filter_by_scope` is a boolean (default `true`): when `false`, the list
methods return every entity and only the calls are refused by scope.
`audience_check` is a boolean (default `true`): when `false`, the gate
skips the check that the audience of the token names this server.

# `initialize_result`

```elixir
@callback initialize_result() ::
  %OzMcp.Structs.InitializeResult{
    _meta: term(),
    capabilities: term(),
    extras: term(),
    instructions: term(),
    protocolVersion: term(),
    serverInfo: term()
  }
  | map()
```

Returns the `t:OzMcp.Structs.InitializeResult.t/0` of the server: the
protocol version, the server information, the capabilities, the
instructions and the root `_meta`. Generated. The framework sends it
as the answer to `initialize`. The application does not implement it.

# `paginate_prompts`

```elixir
@callback paginate_prompts() :: non_neg_integer() | nil
```

Returns the page size of the `prompts` block of the server, or `nil`
when the block has no `paginate`. Generated. The application does not
implement it.

# `paginate_resources`

```elixir
@callback paginate_resources() :: non_neg_integer() | nil
```

Returns the page size of the `resources` block of the server, or
`nil` when the block has no `paginate`. Generated. The application
does not implement it.

# `paginate_templates`

```elixir
@callback paginate_templates() :: non_neg_integer() | nil
```

Returns the page size of the `templates` block of the server, or
`nil` when the block has no `paginate`. Generated. The application
does not implement it.

# `paginate_tools`

```elixir
@callback paginate_tools() :: non_neg_integer() | nil
```

Returns the page size of the `tools` block of the server, or `nil`
when the block has no `paginate`. Generated. The application does not
implement it.

# `roots_list_changed`
*optional* 

```elixir
@callback roots_list_changed(ctx :: OzMcp.Context.ctx()) :: any()
```

Called when a client that declared the `roots` capability sends
`notifications/roots/list_changed`: its list of roots changed.

Optional: the default does nothing. Override it in the server module to
react (for example, call `OzMcp.Client.list_roots/2` to read the new
roots). `ctx` is the short context of the callbacks (without a request id:
the client sent a notification). The function runs in its own process, after
the notification was accepted; its result is ignored and a failure is only
logged.

The calls are bounded (see OzMcp.RootsChanged): at most one run per
session at a time, a burst of notifications that arrives while it runs is
one more run afterwards and a run is stopped at the `request_timeout_ms` of
the server (5 minutes when there is none). Do not rely on one call per
notification: read the roots, do not count the notifications.

There is no request, so there is no response stream for the calls of
`OzMcp.Client`: they need an open `GET` stream of the session and fail with
`{:error, :no_stream}` otherwise. Pass `wait_for_stream: true` to queue the
request for the next stream.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
