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"
endverifier(required) — a module that implements theOzMcp.Authbehaviour. The runtime checks the module and itsauthenticate/2when it starts;authorize/3is optional.authorization_servers(required) — URLs of the authorization servers that can issue a token for this server. At least one entry,httpsonly (httpis accepted for a loopback host). They are published in the Protected Resource Metadata document (seeOzMcp.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 therequired_scopesof the DSL modules instead and omits the field when that union is empty. A client that gets noscopeparameter in a challenge asks for all the scopes of the list: to keep the least privilege, setchallenge_scopesor setscopes_supported.challenge_scopes— the scopes named in theWWW-Authenticateheader of a401or a403when the verifier gives none of its own.filter_by_scope— a boolean, defaulttrue. Whenfalse, the list methods (tools/list,resources/list,resources/templates/listandprompts/list) return every entity: only the calls are refused by scope. SeeOzMcp.Auth.Scopes.audience_check— a boolean, defaulttrue. Whenfalse, 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.