mcp-server · diff

git:20261108.4003aa1 to git:20261108.4d3f8aa

9 added, 4 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: mcp-server
description: "Publish a Mendix app as an MCP server so external agents can call its microflows as tools and use its prompts. Covers runtime configuration with the MCP Server module's Java actions (3.x-4.x: a startup microflow that creates the server and registers tools), the authentication, tool and prompt microflow contracts, and migrating to model configuration. Use when exposing app logic over MCP or reading an existing MCP server setup. To call an external MCP server, see the agents skill."
---
<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->
## Find it fast
`sed -n '<from>,<to>p' SKILL.md` one section rather than reading the file;
`./mxcli syntax <topic>` answers *how do I write this* for a fraction of either.
| lines | section |
|---|---|
| 43-174 | Runtime configuration |
| 175-203 | Gotchas |
- | 204-228 | Reading and migrating an existing setup |
+ | 204-233 | Reading and migrating an existing setup |
<!-- /skill-index -->
# Publishing an MCP Server
An app publishes an MCP server through the **MCP Server** marketplace module.
Two ways to configure it exist:
| | Runtime configuration | Model configuration |
|---|---|---|
| Where it lives | A microflow that runs at startup and calls the module's Java actions | A *Published MCP service* document (Agent Editor), edited in Studio Pro |
| Module versions | MCP Server 3.x and later (measured 3.0.0, 4.0.0, 4.2.2, 5.4.0) | MCP Server 5.x with Agent Editor 2.6+ (measured 5.4.0 / 2.6.0) |
| Prompts | Yes (`AddPrompt`) | No: the document holds tools only |
- | MDL | `call java action MCPServer.*`, below | Not supported yet (ako/mxcli#2020) |
+ | MDL | `call java action MCPServer.*`, below | `create published mcp service` (agents skill) |
The two are the same mechanism. At startup AgentEditorCommons reads every
Published MCP service document and calls `MCPServer.CreateMCPServer` and
`MCPServer.AddTool` with its values (`AgentDocumentUtils.initPublishedMCPService`),
exactly as a runtime-configured app does from its own microflow. So a server
behaves the same either way, and moving between them is a 1:1 mapping (see the
end of this skill).
Runtime configuration is plain microflow logic, so everything mxcli writes for
microflows applies: `describe microflow` reads an existing setup back,
`check --references` validates it, `exec` writes it. Choose it when the server's
tools or prompts depend on data or settings known only at runtime, when it needs
prompts, or when the app is on an MCP Server version before 5.
## Runtime configuration
Four microflows: one authenticates a request, one per tool, one per prompt, and
one starts the server and registers the tools and prompts.
```sql
mdl 1;
-- Authenticate each MCP request: return the user, or empty to refuse it.
create microflow MyModule.MCP_Authenticate (
$HttpRequest: System.HttpRequest,
$McpServer: MCPServer.McpServer
)
returns System.User as $User
begin
retrieve $Headers from $HttpRequest/System.HttpHeaders;
$UserName = find $Headers by Key = 'Username';
$Password = find $Headers by Key = 'Password';
if $UserName = empty or $Password = empty then
return empty;
end if;
retrieve $User from System.User where Name = $UserName/Value first;
if $User = empty then
return empty;
end if;
-- Never let this microflow throw: an error is a 500, which also stops a client's OAuth flow.
$Valid = call java action System.VerifyPassword(userName = $UserName/Value, password = $Password/Value)
on error without rollback begin return empty; end error;
if $Valid then
return $User;
end if;
return empty;
end;
-- A tool: primitive parameters named as in the Schema, returns TextContent.
create microflow MyModule.MCPTool_CountCustomers (
$NamePrefix: String
)
returns MCPServer.TextContent as $Result
begin
retrieve $Customers from MyModule.Customer where starts-with(Name, $NamePrefix);
$Count = count $Customers;
$Result = create MCPServer.TextContent (Content = toString($Count) + ' customers');
return $Result;
end;
-- A prompt: takes MCPServer.Prompt plus its arguments, returns a PromptMessage.
create microflow MyModule.MCPPrompt_CustomerReport (
$Prompt: MCPServer.Prompt,
$CustomerName: String
)
returns MCPServer.PromptMessage as $Message
begin
$Message = create MCPServer.PromptMessage (Role = 'USER', Content = 'Write an account summary for customer ' + $CustomerName + '.');
return $Message;
end;
-- Start the server and register its tools and prompts. Call it after startup.
-- Each call handles its own error, so a server that cannot start logs and
-- returns false instead of stopping the runtime.
create microflow MyModule.MCP_Initialize ()
returns Boolean
begin
$McpServer = call java action MCPServer.CreateMCPServer(
Path = 'customers',
Name = 'Customers',
Version = '1.0.0',
ProtocolVersion = MCPServer.ENUM_ProtocolVersion.v2025_03_26,
AuthenticationMicroflow = 'MyModule.MCP_Authenticate'
) on error without rollback begin
log error node 'MCPServer' 'Could not start the Customers MCP server';
return false;
end error;
$Tool = call java action MCPServer.AddTool(
McpServer = $McpServer,
Name = 'count_customers',
Description = 'Count the customers whose name starts with NamePrefix.',
ExecutingMicroflow = 'MyModule.MCPTool_CountCustomers',
Schema = '{"type": "object", "properties": {"NamePrefix": {"type": "string"}}, "required": ["NamePrefix"]}'
) on error without rollback begin
log error node 'MCPServer' 'Could not register tool count_customers';
return false;
end error;
$Arguments = create list of MCPServer.PromptArgument;
call microflow MCPServer.PopulatePromptArgList(PromptArgumentList = $Arguments, Name = 'CustomerName', Description = 'The customer to summarize', Required = true);
$Prompt = call java action MCPServer.AddPrompt(
McpServer = $McpServer,
Name = 'customer_report',
Description = 'Draft an account summary for one customer.',
Parameters = $Arguments,
Microflow = 'MyModule.MCPPrompt_CustomerReport'
) on error without rollback begin
log error node 'MCPServer' 'Could not register prompt customer_report';
return false;
end error;
return true;
end;
```
Then call `MyModule.MCP_Initialize` from the app's after-startup microflow
(`describe settings` shows which one that is). That is how FactoryManagement
wires it; a server whose initialize microflow nothing calls is never started.
### The contracts
| Microflow | Parameters | Returns |
|---|---|---|
| Authentication | `System.HttpRequest`, optionally `MCPServer.McpServer` | `System.User`; empty refuses the request |
| Tool | Primitives named as the Schema's properties, optionally `MCPServer.Tool` | `MCPServer.TextContent` or a `String` |
| Prompt | `MCPServer.Prompt` plus one primitive per prompt argument | `MCPServer.PromptMessage` |
| Java action | Parameters | Added in 5.x |
|---|---|---|
| `MCPServer.CreateMCPServer` | `Path`, `Name`, `Version`, `ProtocolVersion`, `AuthenticationMicroflow` → `MCPServer.McpServer` | `AuthorizationServerUrl`, `Scopes` (OAuth) |
| `MCPServer.AddTool` | `McpServer`, `Name`, `Description`, `ExecutingMicroflow`, `Schema` → `MCPServer.Tool` | `Title` |
| `MCPServer.AddPrompt` | `Name`, `Description`, `Parameters` (list of `MCPServer.PromptArgument`), `Microflow`, `McpServer` → `MCPServer.Prompt` | — |
**OAuth (5.x).** `AuthorizationServerUrl` is the issuer URL of the OAuth server
that issues the tokens (e.g. `https://login.microsoftonline.com/<tenant-id>/v2.0`);
the server publishes it as Protected Resource Metadata and in its 401 responses,
so a client can find where to sign in. `Scopes` is space-separated and requires
`AuthorizationServerUrl`, which requires an authentication microflow: that
microflow must validate the access token, audience included, and return empty
rather than throw (a throw is a 500, which stops the client's OAuth flow). In
5.x the authentication microflow is optional and both its parameters are
optional; it may return a specialization of `System.User`.
A microflow parameter is passed as its qualified name in quotes, as for any Java
action. In 4.x `Schema` is optional: the module derives it from the tool
microflow's parameters when it is left empty. Write it out when the descriptions
matter to the calling model; the property names must match the parameter names.
## Gotchas
- **`ProtocolVersion` values differ per module version.** 3.0.0 has only
`v2024_11_05`; 4.0.0 and 4.2.2 have only `v2025_03_26`. Read the installed one
with `describe enumeration MCPServer.ENUM_ProtocolVersion`. The module's own
`MCPServer_Initialize` example still names `v2024_11_05` in 4.x, and is
`@excluded` for that reason: copy its shape, not its values.
- **Do not clear `AuthenticationMicroflow` after creating the server.** Some
demo apps follow `CreateMCPServer` with
`change $McpServer (AuthenticationMicroflow = empty)`, which makes the server
usable by anyone who can reach the app. With no authentication microflow the
module applies none.
- **Reserved names and paths.** 4.2.2 documents `sse` and `mcp` as reserved in
the server `Name`; 5.4 refuses a `Path` that is `mcp`, ends in `/mcp`, or
contains `/`.
- **Tools run as the authenticated user (5.4, measured).** A tool that filters
on `$currentUser` returned only that user's data over a live MCP client, so
grant each tool and prompt microflow to the roles those users hold. The 3.0
action documentation said the user was not in scope of a tool microflow.
- **`CreateMCPServer` needs the application root URL.** 5.4 builds the endpoint
from it and throws a NullPointerException when it is unset, as
`mxcli run --local` leaves it for a model holding the stock
`http://localhost:8080/`. Unhandled in an after-startup microflow, that stops
the runtime ("Starting Mendix Runtime failed"), and `mxcli test --local` with
it. Pass `--runtime-setting ApplicationRootUrl=http://localhost:8080/` to
`run --local`, and keep the `on error` handlers above so a server that cannot
start never blocks startup.
- **The client must speak the same protocol version** as `ProtocolVersion`.
## Reading and migrating an existing setup
```sql
list java actions in MCPServer;
describe enumeration MCPServer.ENUM_ProtocolVersion;
list callers of MCPServer.CreateMCPServer;
```
Each `CreateMCPServer` call is one server, and the `AddTool` / `AddPrompt` calls
on its result are its tools and prompts. That inventory is the input for a move
to model configuration. The tool microflows and the authentication microflow
carry over unchanged; the registration calls map onto the document's keys:
| Runtime configuration | Published MCP service document |
|---|---|
| `CreateMCPServer(Path)` | `endpointPath` |
| `Name` / `Version` / `ProtocolVersion` | `serverName` / `version` / `protocolVersion` |
| `AuthenticationMicroflow` | `authenticationEnabled: true` + `authenticationMicroflow` |
| `AuthorizationServerUrl` / `Scopes` | `authorizationServerUrl` / `scopes` (read only when authentication is enabled) |
| each `AddTool(Name, Description, ExecutingMicroflow, Schema, Title)` | a `tools` entry: `name`, `description`, `sourceMicroflow`, `schema`, `title` |
| `AddPrompt` | no equivalent: keep a runtime microflow for prompts |
After the move, remove the initialize call from the after-startup microflow, so
- the server is not created twice. The MDL statement for the document is
- ako/mxcli#2020.
+ the server is not created twice. Write the document with
+ `create published mcp service` (`./mxcli syntax agents.published-mcp-service`):
+ `EndpointPath`, `Version`, `ProtocolVersion`, `AuthenticationEnabled`,
+ `AuthenticationMicroflow`, `AuthorizationServerUrl` and `Scopes` take the
+ values of the `CreateMCPServer` call (its `Name` is `ServerName`, which defaults
+ to the document name), and each `AddTool` becomes a
+ `tool name ( Microflow: …, Description: …, Title: …, Schema: … )` block.