OzMcp.Config.Server.DSL (OzMcp v0.9.0)

Copy Markdown View Source

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).

BlockReserved 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.

Summary

Functions

audience_check(value)

(macro)

authorization(list)

(macro)

authorization_servers(value)

(macro)

cancel(value)

(macro)

capabilities(list)

(macro)

challenge_scopes(value)

(macro)

completions(value)

(macro)

description(value)

(macro)

experimental(value)

(macro)

extra(key, value)

(macro)

filter_by_scope(value)

(macro)

icon(list)

(macro)

instructions(value)

(macro)

list(value)

(macro)

list_result(list)

(macro)

logging(value)

(macro)

meta(key, value)

(macro)

mime_type(value)

(macro)

name(value)

(macro)

paginate(value)

(macro)

prompt(value)

(macro)

prompts(list)

(macro)

protocol_version(value)

(macro)

requests(value)

(macro)

resource(value)

(macro)

resource_documentation(value)

(macro)

resource_name(value)

(macro)

resources(list)

(macro)

scopes_supported(value)

(macro)

server_info(list)

(macro)

sizes(value)

(macro)

src(value)

(macro)

subscribe(value)

(macro)

tasks(list)

(macro)

template(value)

(macro)

templates(list)

(macro)

theme(value)

(macro)

title(value)

(macro)

tool(value)

(macro)

tools(list)

(macro)

verifier(value)

(macro)

version(value)

(macro)

website_url(value)

(macro)