mcp_server

MCP (Model Context Protocol) server library for Logtalk applications. Makes any Logtalk application available as a local MCP server using stdio transport. Implements the MCP 2025-06-18 specification (tools, prompts, resources, elicitation, structured output, and resource links). Supports version negotiation.

The library uses the json_rpc library for JSON-RPC 2.0 message handling as currently required by the MCP specification.

API documentation

Open the ../../apis/library_index.html#mcp_server link in a web browser.

Loading

To load this library, load the loader.lgt file:

| ?- logtalk_load(mcp_server(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(mcp_server(tester)).

Usage

Implementing the tool protocol

To expose a Logtalk object as an MCP tool provider, implement the mcp_tool_protocol protocol:

:- object(my_tools,
    implements(mcp_tool_protocol)).

    :- public(factorial/2).
    :- mode(factorial(+integer, -integer), one).
    :- info(factorial/2, [
        comment is 'Computes the factorial of a non-negative integer.',
        argnames is ['N', 'F']
    ]).

    tools([
        tool(factorial, factorial, 2)
    ]).

    factorial(0, 1) :- !.
    factorial(N, F) :-
        N > 0,
        N1 is N - 1,
        factorial(N1, F1),
        F is N * F1.

:- end_object.

The tools/1 predicate returns a list of tool(Name, Functor, Arity) descriptors that declare which predicates are exposed as MCP tools:

• Name — the MCP tool name (an atom)

• Functor — the predicate functor

• Arity — the predicate arity

Tool descriptions and parameter schemas are automatically derived from the info/2 and mode/2 directives. This must be accurate to allow correct derivation of inout and output arguments and types.

A title key in the predicate’s info/2 directive provides a human-friendly display name for the tool. If omitted, the predicate functor is used as the title.

The supported predicates types and their corresponding JSON types are:

Logtalk type	JSON type
integer	integer
float	number
number	number
atom	string
boolean	boolean
list	array
list(_)	array
compound	object
nonvar	string
term	string
chars	string
codes	string
(other)	string

Auto-dispatch vs. custom tool_call/3

By default, when an MCP client calls a tool, the server auto-dispatches: it calls the corresponding predicate as a message to the application object, collects output-mode arguments (- and --), and returns them as text content.

For custom result formatting, implement tool_call/3:

tool_call(factorial, Arguments, Result) :-
    member('N'-N, Arguments),
    factorial(N, F),
    number_codes(F, Codes),
    atom_codes(FAtom, Codes),
    atom_concat('The factorial is: ', FAtom, Text),
    Result = text(Text).

The Result term can be:

• text(Atom) — a text result

• error(Atom) — a tool-level error (sets isError: true)

• results(List) — a list of content items (text(Atom), error(Atom), resource_link(URI, Name), or resource_link(URI, Name, Description, MimeType))

• structured(StructuredContent) — a structured result (the server auto-generates a text representation for the content field)

• structured(Items, StructuredContent) — a structured result with explicit content items for the content field

Output schemas (structured tool output)

Tools can declare an output schema by defining output_schema/2 in their application object:

output_schema(divide, {type-object, properties-{quotient-{type-number}}, required-[quotient]}).

When an output schema is declared, the tool descriptor includes an outputSchema field. The tool’s tool_call/3 can then return structured(StructuredContent) or structured(Items, StructuredContent) results. The StructuredContent must be a curly-term matching the schema.

Starting the server for debugging

Start the MCP server from a Logtalk top-level or script:

| ?- mcp_server::start('my-server', my_tools).

With options:

| ?- mcp_server::start('my-server', my_tools, [version('2.0.0'), server_title('My Server')]).

There should either be no output or only a Prolog backend term input prompt. Other than that, any spurious output will break the connection between a MCP client and the MCP server.

MCP client configuration

To use the server with an MCP client (e.g., VSCode or Claude Desktop), configure it as a stdio server. Example claude_desktop_config.json:

{
    "mcpServers": {
        "my-server": {
            "command": "swilgt",
            "args": [
                "-q",
                "-g", "logtalk_load(my_mcp_server(loader))",
                "-t", "halt"
            ],
            "env": {
                "LOGTALKHOME": "/usr/local/share/logtalk",
                "LOGTALKUSER": "/Users/jdoe/logtalk"
            }
        }
    }
}

The env definition of the LOGTALKHOME and LOGTALKUSER environment variables may or may not be required (it’s usually necessary on macOS). When required, replace the values above with the actual values on your Logtalk setup.

The actual arguments to the integration script (swilgt in the example above) depend on the Prolog backend. For example, XVM requires instead:

{
    "mcpServers": {
        "my-server": {
            "command": "xvmlgt",
            "args": [
                "-q",
                "-g", "logtalk_load(my_mcp_server(loader)), halt.",
            ],
            "env": {
                "LOGTALKHOME": "/usr/local/share/logtalk",
                "LOGTALKUSER": "/Users/jdoe/logtalk"
            }
        }
    }
}

Elicitation (interactive tools)

Tools that need to ask the user questions during execution can use MCP elicitation if the MCP client supports it (tested and working with VSCode Copilot). The application declares the elicitation capability and implements tool_call/4 instead of tool_call/3:

:- object(interactive_tools,
    implements(mcp_tool_protocol)).

    capabilities([elicitation]).

    tools([
        tool(ask_name, ask_name, 0)
    ]).

    :- public(ask_name/0).
    :- info(ask_name/0, [
        comment is 'Asks the user for their name and greets them.'
    ]).

    tool_call(ask_name, _Arguments, Elicit, Result) :-
        Schema = {
            type-object,
            properties-{name-{type-string}},
            required-[name]
        },
        call(Elicit, 'What is your name?', Schema, Answer),
        (   Answer = accept(Content),
            has_pair(Content, name, Name) ->
            atom_concat('Hello, ', Name, Greeting),
            atom_concat(Greeting, '!', Text),
            Result = text(Text)
        ;   Result = text('No name provided.')
        ).

    has_pair({Pairs}, Key, Value) :-
        curly_member(Key-Value, Pairs).

    curly_member(Pair, (Pair, _)) :- !.
    curly_member(Pair, (_, Rest)) :-
        !, curly_member(Pair, Rest).
    curly_member(Pair, Pair).

:- end_object.

The Elicit closure is called as call(Elicit, Message, Schema, Answer) where:

• Message — an atom with the prompt text

• Schema — a curly-term JSON Schema for the requested input

• Answer — unified with accept(Content), decline, or cancel

When accept(Content) is returned, Content is a curly-term with the user’s response matching the requested schema.

See the examples/birds_mcp/ example for a complete demonstration of elicitation with a bird identification expert system.

Prompts (prompt templates)

MCP prompts are templates for structured LLM interactions. They allow an application to expose reusable prompt templates that MCP clients can discover and use. To add prompts, implement mcp_prompt_protocol in addition to mcp_tool_protocol, and declare prompts in capabilities:

:- object(my_prompts,
    implements([mcp_tool_protocol, mcp_prompt_protocol])).

    capabilities([prompts]).

    tools([]).

    prompts([
        prompt(code_review, 'Reviews code for potential issues', [
            argument(code, 'The code to review', true),
            argument(language, 'The programming language', false)
        ]),
        prompt(summarize, 'Summarizes a given text', [
            argument(text, 'The text to summarize', true)
        ])
    ]).

    prompt_get(code_review, Arguments, Result) :-
        (   member(code-Code, Arguments) ->
            atom_concat('Please review the following code for potential issues:\n\n', Code, Text)
        ;   Text = 'Please provide code to review.'
        ),
        Result = messages([message(user, text(Text))]).

    prompt_get(summarize, Arguments, Result) :-
        (   member(text-Text, Arguments) ->
            atom_concat('Please summarize the following text:\n\n', Text, PromptText)
        ;   PromptText = 'Please provide text to summarize.'
        ),
        Result = messages([message(user, text(PromptText))]).

    :- uses(list, [member/2]).

:- end_object.

The prompts/1 predicate returns a list of prompt descriptors:

• prompt(Name, Description, Arguments) — without title

• prompt(Name, Title, Description, Arguments) — with title

Where:

• Name — the MCP prompt name (an atom)

• Title — a human-friendly display name (an atom, optional)

• Description — a human-readable description (an atom)

• Arguments — a list of argument(ArgName, ArgDescription, Required) terms where Required is true or false

The prompt_get/3 predicate handles prompt get requests. Its result term can be:

• messages(MessageList) — a list of prompt messages

• messages(Description, MessageList) — a list of messages with a description

Each message in the list is a message(Role, Content) term where:

• Role — user or assistant

• Content — text(Text) where Text is an atom

Multi-turn prompts can return multiple messages:

prompt_get(debate, Arguments, Result) :-
    member(topic-Topic, Arguments),
    atom_concat('Let us debate: ', Topic, UserText),
    Result = messages([
        message(user, text(UserText)),
        message(assistant, text('I would be happy to debate that topic. What is your position?'))
    ]).

Resources (data exposure)

MCP resources expose data and content from the application that MCP clients can access. To add resources, implement mcp_resource_protocol in addition to mcp_tool_protocol, and declare resources in capabilities:

:- object(my_resources,
    implements([mcp_tool_protocol, mcp_resource_protocol])).

    capabilities([resources]).

    tools([]).

    resources([
        resource('logtalk://my-app/config', config, 'Application configuration', 'application/json'),
        resource('logtalk://my-app/readme', readme, 'Application readme', 'text/plain')
    ]).

    resource_read('logtalk://my-app/config', _Arguments, Result) :-
        Result = contents([
            text_content('logtalk://my-app/config', 'application/json', '{"name": "my-app", "version": "1.0"}')
        ]).

    resource_read('logtalk://my-app/readme', _Arguments, Result) :-
        Result = contents([
            text_content('logtalk://my-app/readme', 'text/plain', 'Welcome to my application.')
        ]).

:- end_object.

The resources/1 predicate returns a list of resource descriptors:

• resource(URI, Name, Description, MimeType) — without title

• resource(URI, Name, Title, Description, MimeType) — with title

Where:

• URI — the resource identifier (an atom, typically a URI like logtalk://my-app/data)

• Name — a human-readable name (an atom)

• Title — a human-friendly display name (an atom, optional)

• Description — a human-readable description (an atom)

• MimeType — the MIME type of the resource content (an atom, e.g. 'text/plain', 'application/json')

The resource_read/3 predicate handles resource read requests. Its result term must be contents(ContentList) where each content item is:

• text_content(URI, MimeType, Text) — for text resources

• blob_content(URI, MimeType, Base64Data) — for binary resources encoded as base64

A resource can return multiple content items:

resource_read('logtalk://my-app/logs', _Arguments, Result) :-
    Result = contents([
        text_content('logtalk://my-app/logs', 'text/plain', 'Log entry 1'),
        text_content('logtalk://my-app/logs', 'text/plain', 'Log entry 2')
    ]).

Error handling

• Predicate failures result in a tool-level error with isError: true.

• Predicate exceptions result in a tool-level error with the exception term serialized as the error text.

• Prompt execution failures result in a JSON-RPC error response.

• Resource read failures result in a JSON-RPC error response.

Protocol

The mcp_tool_protocol protocol defines the following predicates:

• capabilities/1 — returns the list of additional capabilities needed by the application (e.g. [elicitation], [prompts], [resources], or [prompts, resources, elicitation]); optional, defaults to []

• tools/1 — returns the list of tool descriptors

• tool_call/3 — handles a tool call (optional; auto-dispatch is used when not defined)

• tool_call/4 — handles a tool call with an elicitation closure (optional; requires capabilities([elicitation]) or capabilities([..., elicitation]))

• output_schema/2 — declares a JSON Schema for structured tool output (optional; when defined, the tool descriptor includes outputSchema)

The mcp_prompt_protocol protocol defines the following predicates:

• prompts/1 — returns the list of prompt descriptors

• prompt_get/3 — handles a prompt get request

The mcp_resource_protocol protocol defines the following predicates:

• resources/1 — returns the list of resource descriptors

• resource_read/3 — handles a resource read request

Supported MCP methods

Method	Type	Description
initialize	Request	MCP handshake
initialized	Notification	Client acknowledgment
ping	Request	Server liveness check
tools/list	Request	Lists available tools
tools/call	Request	Calls a tool
prompts/list	Request	Lists available prompts
prompts/get	Request	Gets a prompt with arguments
resources/list	Request	Lists available resources
resources/read	Request	Reads a resource by URI
elicitation/create	Request (=>)	Asks the client for user input