---
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-161 | Runtime configuration |
| 162-182 | Gotchas |
| 183-207 | 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) |

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;
  $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 | 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 `/`.
- **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;
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.
