`mcp_tool_protocol`

Protocol for Logtalk objects that provide tools to be exposed via an MCP (Model Context Protocol) server. Implementing objects must define the set of tools available and handle tool calls. Tool metadata (names, titles, descriptions, input and output schemas) can be derived automatically from info/2 and mode/2 directives on the tool predicates, or overridden using input_schema/2 and output_schema/2. Used by both the 2025-06-18 and 2026-07-28 adapters.

| Availability: | logtalk_load(mcp_server(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-09-02

| Compilation flags: | static

| Dependencies: | (none)

| Remarks:

Capabilities: Objects can optionally define capabilities/1 to declare additional application features. Currently supported: prompts, resources, and completions (server capabilities advertised during initialization) and elicitation (a required client capability that allows the server to ask the user questions during tool execution under the 2025-06-18 adapter). If capabilities/1 is not defined, only the tools server capability is advertised.
Tool title: The tool title (human-friendly display name) is derived from a title key in the predicate info/2 directive. If not specified, the predicate name (functor) is used as the title.
Schemas: Input and output schemas are inferred from the tool predicate info/2 and mode/2 directives. Define input_schema/2 or output_schema/2 to override the inferred schema for a tool. Tools can return structured(StructuredContent) or structured(ContentItems, StructuredContent) results; the structured content is included in the structuredContent field of the tool call response alongside the content array.
Resource links: Tool results can include resource_link(URI, Name) or resource_link(URI, Name, Description, MimeType) content items in results/1 lists.
Elicitation (2025-06-18 only): Under the 2025-06-18 adapter, tools that need user interaction during execution should define tool_call/4 instead of tool_call/3. The extra argument is an elicitation closure that can be called as call(Elicit, Message, Schema, Answer) where Message is the prompt text (an atom), Schema is a JSON Schema curly-term for the requested input, and Answer is unified with accept(Content), decline, or cancel. The 2026-07-28 adapter never invokes tool_call/4; multi-round interaction is provided by mcp_multiround_protocol instead.
Multi-round (2026-07-28): For the 2026-07-28 adapter, applications that need additional input during a tool call implement tool_call_round/4 from the mcp_multiround_protocol. Existing tool_call/3 and auto-dispatch remain valid and are wrapped as complete results when the round hook is absent.

| Inherited public predicates: | (none)

.. contents:: :local: :backlinks: top

Public predicates

.. index:: capabilities/1 .. _mcp_tool_protocol/0::capabilities/1:

capabilities/1 ^^^^^^^^^^^^^^^^^^

Returns a list of additional MCP features used by this provider. prompts, resources, and completions are advertised as server capabilities. elicitation declares that the provider may ask the user questions and is enabled only when the client advertises the corresponding client capability. If not defined, only the tools server capability is advertised.

| Compilation flags: | static

| Template: | capabilities(Capabilities) | Mode and number of proofs: | capabilities(-list(atom)) - one

.. index:: tools/1 .. _mcp_tool_protocol/0::tools/1:

tools/1 ^^^^^^^^^^^

Returns a list of tool descriptors available from this object. Each descriptor is a compound term tool(Name, Functor, Arity) where Name is the MCP tool name (an atom), Functor is the predicate functor, and Arity is the predicate arity. By default, the tool name is the predicate functor. Tool titles are derived from info/2 title keys (falling back to the predicate name). Tool descriptions and parameter schemas are derived from the info/2 and mode/2 directives of the corresponding predicates.

| Compilation flags: | static

| Template: | tools(Tools) | Mode and number of proofs: | tools(-list(compound)) - one

.. index:: tool_call/3 .. _mcp_tool_protocol/0::tool_call/3:

tool_call/3 ^^^^^^^^^^^^^^^

Handles a tool call. Name is the MCP tool name (as declared in tools/1), Arguments is a list of ArgumentName-Value pairs, and Result is unified with the tool result. The result must be one of: text(Atom) for a text result, error(Atom) for an error result, results(List) for a list of content items where each item is text(Atom), error(Atom), resource_link(URI, Name), or resource_link(URI, Name, Description, MimeType), structured(StructuredContent) for structured output with auto-generated text, or structured(ContentItems, StructuredContent) for structured output with explicit content items. If this predicate is not defined for a tool, the MCP server will use auto-dispatch: it calls the tool predicate as a message to the implementing object, collects output arguments, and returns them as a text result.

| Compilation flags: | static

| Template: | tool_call(Name,Arguments,Result) | Mode and number of proofs: | tool_call(+atom,+list(pair),--compound) - one

.. index:: tool_call/4 .. _mcp_tool_protocol/0::tool_call/4:

tool_call/4 ^^^^^^^^^^^^^^^

Handles a tool call with elicitation support under the 2025-06-18 adapter only. Same as tool_call/3 but receives an Elicit closure as the third argument. The closure can be called as call(Elicit, Message, Schema, Answer) where Message is a prompt text (an atom), Schema is a curly-term JSON Schema describing the requested input (e.g., {type-object, properties-{answer-{type-string, enum-[yes, no]}}, required-[answer]}), and Answer is unified with accept(Content) (where Content is the user response as a curly-term), decline, or cancel. Only available when the application declares elicitation in its capabilities/1 and the client advertises elicitation support during initialization. Falls back to tool_call/3 and then auto-dispatch if not defined. The 2026-07-28 adapter never calls this predicate; use tool_call_round/4 from mcp_multiround_protocol instead.

| Compilation flags: | static

| Template: | tool_call(Name,Arguments,Elicit,Result) | Mode and number of proofs: | tool_call(+atom,+list(pair),+callable,--compound) - one

.. index:: output_schema/2 .. _mcp_tool_protocol/0::output_schema/2:

output_schema/2 ^^^^^^^^^^^^^^^^^^^

Returns the JSON output schema for the given tool name. Optional; when defined, the schema overrides the one inferred from the tool predicate info/2 and mode/2 directives. The tool can return structured(StructuredContent) or structured(ContentItems, StructuredContent) results. The schema must be a curly-term following JSON Schema format (e.g. {type-object, properties-{temperature-{type-number}}, required-[temperature]}).

| Compilation flags: | static

| Template: | output_schema(Name,Schema) | Mode and number of proofs: | output_schema(+atom,-compound) - zero_or_one

.. index:: input_schema/2 .. _mcp_tool_protocol/0::input_schema/2:

input_schema/2 ^^^^^^^^^^^^^^^^^^

Returns the JSON input schema for the given tool name. Optional; when defined, the schema overrides the one inferred from the tool predicate info/2 and mode/2 directives. The schema must be a curly-term following JSON Schema format (e.g. {type-object, properties-{temperature-{type-number}}, required-[temperature]}).

| Compilation flags: | static

| Template: | input_schema(Name,Schema) | Mode and number of proofs: | input_schema(+atom,-compound) - zero_or_one

Protected predicates

(none)

Private predicates

(none)

Operators

(none)