Behaviour for MCP tool modules.
Two ways to declare the tools
| Way | use | What you write | What the framework generates |
|---|---|---|---|
| DSL | use OzMcp.Config.Tool | one tool "name" do ... end block for each tool and call/2 | list/0. The DSL checks the schemas at compile time. |
| Data | use OzMcp.Config.Tool, dsl?: false | list/0 that returns %OzMcp.Structs.Tool{} structs or maps with the wire keys (name, inputSchema, ...) and call/2 | nothing |
Rules for the way with dsl?: false:
- A map carries
required_scopeslike a struct: the boot of the instance reads the key, checks it and it never reaches the client. - The boot check of duplicate names reads
list/0of a module one time at boot.
The guide Tools shows an example of each way.
Static schemas and schema validation
The server reads a module one time, at the boot of the instance and answers a lookup from a map in the catalog. A change of a module needs a stop and a start of the instance.
A dsl?: true tool (the default) that declares an invalid
inputSchema or outputSchema fails at compile time; the root of
each schema must have the type "object". A tool with dsl?: false
is checked at the boot of the instance. The guide
Tools gives the details of each check.
Output schema
When a tool declares an outputSchema, the server checks each result
of the tool before it sends the result:
- A result with
isError: trueis not checked. - Each other result must have a
structuredContentthat is an object and that agrees with theoutputSchema. - The check uses the JSON form of
structuredContent: atom keys and atom values are strings, as on the wire.
A result that does not obey these rules gives the JSON-RPC error
-32603 "tool output does not match outputSchema". The data of
the error holds the messages. A task-augmented call gets the same
check: the task becomes failed and tasks/result gives the same
error.
Required scopes
Declare required_scopes [...] in a tool block: a tools/call
without all the scopes gets 403 and tools/list hides the tool
from a principal that lacks them. A tool declared with dsl?: false
carries the scopes in the key required_scopes of a map, or in the
field of the struct. The guide about the authorization gives the
rules of the scopes and of the filter of the lists.
Unique key
The name of a tool is unique in the module: two tools with the same
name raise at compile time. The name is unique in the server too:
the runtime refuses to boot when two tool modules of one server
declare the same name. The boot check reads list/0 of each
module.
Summary
Callbacks
Runs the tool params["name"] with the arguments
params["arguments"].
Returns the tools of the module: %OzMcp.Structs.Tool{} structs, or
maps with the wire keys.
Types
Callbacks
@callback call(OzMcp.Context.ctx(), rpc_params()) :: call_result()
Runs the tool params["name"] with the arguments
params["arguments"].
params is the full params object of tools/call. The input
schema of the tool checked the arguments and gave the default
values, before the call.
Return:
{:ok, %CallToolResult{}}or{:ok, map}: the result of the tool. SetisError: truefor an error that the model can correct.{:error, %OzMcp.Utils.Error{}}: a protocol error, for example an unknown tool (-32602).
Each other return value gives the client a -32603 error. The
callback runs in a supervised process of its own, after the request
process.
Example
@impl true
def call(_ctx, %{"name" => "echo", "arguments" => %{"text" => text}}) do
{:ok, %{content: [%{type: "text", text: text}]}}
end
@callback list() :: [ %OzMcp.Structs.Tool{ _meta: term(), annotations: term(), description: term(), execution: term(), extras: term(), icons: term(), inputSchema: term(), name: term(), outputSchema: term(), required_scopes: term(), title: term() } ] | [map()]
Returns the tools of the module: %OzMcp.Structs.Tool{} structs, or
maps with the wire keys.
The DSL generates it. The boot of the instance calls it one time.