---
name: mcp-server
description: "Publish a Mendix app as an MCP server, so external agents (Claude Desktop, other apps) can call its microflows as tools and use its prompts. Covers runtime configuration with the MCP Server module's Java actions (module 3.x-4.x, a startup microflow that creates the server and registers tools), the authentication microflow, tool and prompt microflow signatures, and how this relates to model configuration in newer versions. Use when exposing app logic over MCP, or reading or migrating an existing MCP server setup. For calling an external MCP server from an agent, see the agents skill (consumed mcp service)."
---
<!-- 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 |
|---|---|
| 35-143 | Runtime configuration |
| 144-163 | Gotchas |
| 164-177 | 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 document in the model, edited in Studio Pro |
| Module versions | MCP Server 3.x and 4.x (measured 3.0.0, 4.0.0, 4.2.2) | MCP Server 5.x with Agent Editor (OAuth) |
| MDL | `call java action MCPServer.*`, below | Not supported yet (ako/mxcli#2020) |

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 depend on data or settings known only at runtime, 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;
  $Valid = call java action System.VerifyPassword(userName = $UserName/Value, password = $Password/Value);
  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.
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'
  );
  $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"]}'
  );
  $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'
  );
  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 |
|---|---|
| `MCPServer.CreateMCPServer` | `Path`, `Name`, `Version`, `ProtocolVersion`, `AuthenticationMicroflow` → `MCPServer.McpServer` |
| `MCPServer.AddTool` | `McpServer`, `Name`, `Description`, `ExecutingMicroflow`, `Schema` → `MCPServer.Tool` |
| `MCPServer.AddPrompt` | `Name`, `Description`, `Parameters` (list of `MCPServer.PromptArgument`), `Microflow`, `McpServer` → `MCPServer.Prompt` |

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.
- **Avoid `sse` and `mcp` in the server `Name`.** 4.2.2 documents both words as
  reserved.
- **The current user in a tool microflow depends on the version.** The 3.0
  action documentation says the user is not in scope of a tool or prompt
  microflow; 4.x drops that sentence. FactoryManagement grants its tool
  microflows to the role its authenticated users hold.
- **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;
show 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 also the input for a
move to model configuration: the tool microflows and the authentication logic
carry over, the registration calls are what model configuration replaces. MDL
for the model-configured document follows once its storage is measured
(ako/mxcli#2020).
