Skip to main content
Version: 7.0

MCP server setup

The lsFusion platform can act as an MCP server (Model Context Protocol) for external AI clients (for example, claude.ai). The MCP server runs on top of the standard HTTP API of the platform, so no separate service has to be deployed — it is enough to configure two parameters on the application server: enableAPI and HTTPS. The /mcp endpoint itself is served by the web server (Client) of the application, not by the HTTP port of the application server — see URL example.

1. The enableAPI parameter​

This parameter controls access to the program interface through which the MCP client talks to the server (eval/action, exec, etc.). For the full description, see Working parameters.

ValueBehavior
0API is fully disabled (default)
1Only authenticated access is allowed
2Anonymous access is allowed — acceptable only on dev / sandbox installations

The value 2 must not be used for the production application: it opens the API without authorization.

The recommended way to configure enableAPI in production is to keep it 0 globally and set it to 1 only for the roles that actually need to work through the MCP client (typically Administrator, or a dedicated role created specifically for AI access). Then only users assigned to those roles can use the MCP server.

This is done at runtime through the form Administration > System > Settings > Parameters — the enableAPI parameter with the value 1 is bound to the required role (the per-role settings mechanism is described in Working parameters).

Alternative ways to set the value​

If per-role configuration is not an option for some reason, enableAPI can be set in one of the standard ways (in order of increasing priority — see Working parameters):

  • In the project's lsfusion.properties — settings.enableAPI=1.
  • In conf/settings.properties of a specific installation — settings.enableAPI=1.
  • In the Java startup parameters of the application server — -Dsettings.enableAPI=1.
  • Globally in the Administration > System > Settings > Parameters form (without binding to a role).

The highest priority is given to the value set in the database (the Parameters form), so in case of a mismatch with the value in *.properties files, the database value wins.

2. HTTPS is mandatory​

warning

Connecting the MCP server to claude.ai (or to any other external MCP client) is allowed only over HTTPS. Publishing the MCP endpoint over http:// is not permitted.

HTTPS deployment is done according to the scheme described at the end of the Automatic installation page. The MCP server URL configured in the MCP client must start with https:// and resolve to a public DNS address with a valid certificate — self-signed certificates do not work, the client will refuse to establish a connection.

URL example​

The MCP server endpoint corresponds to the /mcp path on the web server (Client) of the production application. The URL configured in the MCP client is built as:

https://<web server url>/mcp

For example, if the application is deployed at https://erp.example.com, the URL to register in the MCP client will be:

https://erp.example.com/mcp

Authorization discovery on a non-root deployment​

When the API requires authentication (enableAPI=1), /mcp starts OAuth discovery by returning 401 with a WWW-Authenticate: Bearer challenge. The challenge includes resource_metadata, pointing to the protected-resource metadata document:

https://host/<context>/.well-known/oauth-protected-resource

The metadata URLs are built from the request's external base URL (scheme://host[:port][/contextPath], including forwarded proto/host headers), so the JSON contents are correct for a deployment under a context path. For example, under https://host/lsfusion, the protected-resource metadata says that the resource is https://host/lsfusion and that its authorization server is also https://host/lsfusion.

The discovery chain is therefore:

POST /lsfusion/mcp
-> 401 WWW-Authenticate: Bearer resource_metadata="https://host/lsfusion/.well-known/oauth-protected-resource"
GET /lsfusion/.well-known/oauth-protected-resource
-> authorization_servers: ["https://host/lsfusion"]
GET /.well-known/oauth-authorization-server/lsfusion
-> authorization-server metadata

The non-root deployment problem is the last step. For an issuer with a path, RFC 8414 §3.1 puts the well-known segment at the host root and appends the issuer path after it, so a strict client looks for:

https://host/.well-known/oauth-authorization-server/lsfusion

A Java web application deployed under /lsfusion only owns /lsfusion/*, so the platform naturally serves the metadata at the in-context URL instead:

https://host/lsfusion/.well-known/oauth-authorization-server

The metadata document itself is correct once reached. Only the strict discovery URL is outside the web application's context. The protected-resource metadata URL emitted by the platform's WWW-Authenticate header is already in-context, so that hop works without a rewrite.

A strict OAuth client does not fall back from the RFC 8414 host-root URL to the in-context URL on a 404: it stops discovery, and the user sees a generic "couldn't reach the server" error with no useful server-side log. The claude.ai connector behaves this way.

Fix this at the HTTP layer in front of the application (a reverse proxy, ingress, or the servlet container) — not in application code — by rewriting the host-root authorization-server discovery URL back into the application context. For a Tomcat host-level RewriteValve:

RewriteRule ^/\.well-known/oauth-authorization-server/(.+)$ /$1/.well-known/oauth-authorization-server [L]
RewriteRule ^/\.well-known/openid-configuration/(.+)$ /$1/.well-known/oauth-authorization-server [L]

The rules are generic: the captured path is the context path, so they work for /lsfusion, /mycompany, and other non-root deployments. The same rewrite can be implemented in a reverse proxy or ingress. The second rule aliases OIDC discovery to the same OAuth authorization-server metadata document, because some clients try the OIDC well-known URL during discovery.

note

Root-context deployments, where the application is served directly at https://host (as in the https://erp.example.com example above), do not need these rewrites: the host-root and in-context URLs collapse to the same /.well-known/oauth-authorization-server.

Browser agent: WebMCP​

The AI agent built into the browser gets the same tools — through WebMCP, in a browser that has document.modelContext. Nothing has to be turned on for that: as it opens, the page of the web client registers with the browser every tool the MCP server of the application lists, and the agent calls them on behalf of the user logged in to the application — in the user's web session, with no connection of its own and no OAuth. The agent's access to each tool is that of an external MCP client connected on behalf of this user (see the enableAPI parameter).

A tool is the server's: its description, its parameters and its result are the ones /mcp gives, and it runs on the server, as when called through /mcp. The page does one thing itself: it runs the script of lsfusion_eval, and the action of lsfusion_exec, where the user works. Where they run is set by the context parameter of the tool:

contextWhere the script runsChange session
logicsOn the serverA new one per call: the changes are discarded unless the script applies them itself
navigatorIn the navigator, as an action the user startedA new one per call: the changes are discarded unless the script applies them itself
formIn a form — the one the form parameter addresses, otherwise the form the user is in —, as an action the user startedThe form's session: the script sees its unapplied changes, and its own changes are shown in the form and applied together with the form's changes

In navigator and form, a form the script shows opens in the user's browser, and a message or a dialog is shown to the user, the call waiting for the answer (a message shown with NOWAIT is not waited for). So there the script gives the agent a value as the result of the action, not in a message. In form, an APPLY or a CANCEL in the script acts on the form's session as a whole, the user's unsaved changes included. In logics there is nobody to show a message to: the messages are returned in the tool's result.

When neither context nor form is set, the page runs the script in the form the user is in, and in the navigator when there is no such form. The form parameter addresses one open form by any of its name (name), the label it was opened with (label) and the window it was opened into (window), as the ACTIVATE FORM operator does; the call fails when the address names no form, or several. The page shows the address in the attributes of the form's element: lsfusion-form (the name), lsfusion-form-label and lsfusion-form-window. Through /mcp only logics is there: a call with navigator, form or the address of a form is refused. In a form, lsfusion_exec looks the name of the action up first among what the form exposes to its page (the CUSTOMS block), and runs such an action whatever enableAPI is, as the form's own page does.

The parameters of the script and the result of the tool are the same in every context, and the result does not say where the script ran. A text of 64 KiB and more is returned beside the result, as a resource, in logics, and in the result itself in navigator and form, where the link of a file too big to be in the result works in the user's web session.