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

Compile-time macros of a server module (`use OzMcp.Config.Server`).

The root blocks are `protocol_version/1`, `instructions/1`,
`server_info/1`, `capabilities/1`, `tools/1`, `resources/1`,
`templates/1`, `prompts/1`, `meta/2`, `extra/2` and `authorization/1`.
The `capabilities/1` block holds `resources` (with `subscribe`),
`completions`, `logging` and `tasks`. The values of `completions` and
`logging` are the empty map `%{}`. A block declared twice raises at
compile time and so does a property outside its block.

A module that a `tools`, `resources`, `templates` or `prompts` block
lists two times raises at compile time. The key of an entity (the
`name` of a tool or of a prompt, the `uri` of a resource, the
`uri_template` of a template) is unique in its module and in the
server: the runtime refuses to boot when two modules of the same kind
declare the same key.

## Imports

`use OzMcp.Config.Server` imports the root macros only: the blocks of
the list above and `meta/2` with `extra/2`. The nested macros
(`name/1`, `title/1`, `version/1`, `list_result/1`, `icon/1`,
`tool/1`, `paginate/1` and the others) are not imported: they work
only inside their block. A nested macro at the root of the module
gives a compile error (`undefined function name/1`). The server module
can declare a local function with the name of a nested macro (for
example `def name(text), do: text`) and call it.

## `meta` and `extra`

`meta/2` and `extra/2` work at the root of the module and inside each
`list_result` block. The key is a string, or an atom that becomes a
string (`meta :beta, "x"` is the same as `meta "beta", "x"`). The
keys `nil`, `true` and `false` are refused: they are values, not
names. A key declared two times in one block raises at compile time.

The value keeps `true`, `false` and `nil` (they become the JSON
`true`, `false` and `null`). Another atom becomes a string
(`meta "kind", :fast` stores `"fast"`). The other terms do not change.

An `extra` key that names a field of the result of the block is
refused at compile time: it would make a second JSON key with the
same name. Use the field itself (and `meta` for `_meta`).

| Block | Reserved `extra` keys |
|---|---|
| root | `_meta`, `protocolVersion`, `capabilities`, `serverInfo`, `instructions` |
| `tools > list_result` | `_meta`, `tools`, `nextCursor` |
| `resources > list_result` | `_meta`, `resources`, `nextCursor` |
| `templates > list_result` | `_meta`, `resourceTemplates`, `nextCursor` |
| `prompts > list_result` | `_meta`, `prompts`, `nextCursor` |

## The `authorization` block

Declares that the server is protected and how. A server with no block
is open: no request is refused and `authorization/0` of the server
module returns `nil`.

    authorization do
      verifier MyApp.AuthVerifier
      authorization_servers ["https://auth.example.com"]
      scopes_supported ["files:read", "files:write"]
      challenge_scopes ["files:read"]
      filter_by_scope false
      audience_check false
      resource_name "My App MCP server"
      resource_documentation "https://docs.example.com/mcp"
    end

* `verifier` (required) — a module that implements the `OzMcp.Auth`
  behaviour. The runtime checks the module and its `authenticate/2`
  when it starts; `authorize/3` is optional.
* `authorization_servers` (required) — URLs of the authorization
  servers that can issue a token for this server. At least one entry,
  `https` only (`http` is accepted for a loopback host). They are
  published in the Protected Resource Metadata document
  (see `OzMcp.Auth.Metadata`).
* `scopes_supported` — the scopes the server knows; published in the
  metadata document. Each entry must match the RFC 6749 scope-token
  syntax. When the key is absent, the document names the union of the
  `required_scopes` of the DSL modules instead and omits the field
  when that union is empty. A client that gets no `scope` parameter
  in a challenge asks for all the scopes of the list: to keep the
  least privilege, set `challenge_scopes` or set `scopes_supported`.
* `challenge_scopes` — the scopes named in the `WWW-Authenticate`
  header of a `401` or a `403` when the verifier gives none of its own.
* `filter_by_scope` — a boolean, default `true`. When `false`, the list
  methods (`tools/list`, `resources/list`, `resources/templates/list`
  and `prompts/list`) return every entity: only the calls are refused
  by scope. See `OzMcp.Auth.Scopes`.
* `audience_check` — a boolean, default `true`. When `false`, the gate
  skips the check that the audience of the token (`aud`, RFC 8707)
  names this server. See OzMcp.Auth.Audience.
* `resource_name`, `resource_documentation` — optional fields of the
  metadata document (the second one is an http(s) URL).

The canonical URL of the endpoint is not part of the block: it is the
runtime option `:resource_url` of `OzMcp`, so a release can
read it from the environment. The runtime refuses to boot when the
block is declared without it, or when it is set without the block.

# `audience_check`
*macro* 

# `authorization`
*macro* 

# `authorization_servers`
*macro* 

# `cancel`
*macro* 

# `capabilities`
*macro* 

# `challenge_scopes`
*macro* 

# `completions`
*macro* 

# `description`
*macro* 

# `experimental`
*macro* 

# `extra`
*macro* 

# `filter_by_scope`
*macro* 

# `icon`
*macro* 

# `instructions`
*macro* 

# `list`
*macro* 

# `list_result`
*macro* 

# `logging`
*macro* 

# `meta`
*macro* 

# `mime_type`
*macro* 

# `name`
*macro* 

# `paginate`
*macro* 

# `prompt`
*macro* 

# `prompts`
*macro* 

# `protocol_version`
*macro* 

# `requests`
*macro* 

# `resource`
*macro* 

# `resource_documentation`
*macro* 

# `resource_name`
*macro* 

# `resources`
*macro* 

# `scopes_supported`
*macro* 

# `server_info`
*macro* 

# `sizes`
*macro* 

# `src`
*macro* 

# `subscribe`
*macro* 

# `tasks`
*macro* 

# `template`
*macro* 

# `templates`
*macro* 

# `theme`
*macro* 

# `title`
*macro* 

# `tool`
*macro* 

# `tools`
*macro* 

# `verifier`
*macro* 

# `version`
*macro* 

# `website_url`
*macro* 

---

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