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
enduse 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: theOzMcp.Structs.InitializeResult.t/0of the server.authorization/0: the map of theauthorizationblock, ornil.- For each kind (
tools,resources,templates,prompts):paginate_<kind>/0. For examplepaginate_tools/0. list_<kind>_result_meta/0andlist_<kind>_result_extras/0for thelist_resultblock 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.
Summary
Callbacks
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.
Returns the 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.
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.
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.
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.
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.
Called when a client that declared the roots capability sends
notifications/roots/list_changed: its list of roots changed.
Types
Callbacks
@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.
@callback initialize_result() :: %OzMcp.Structs.InitializeResult{ _meta: term(), capabilities: term(), extras: term(), instructions: term(), protocolVersion: term(), serverInfo: term() } | map()
Returns the 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.
@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.
@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.
@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.
@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.
@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.