Agents on ScipioERP

Agent quickstart

Tue, 08 Sep 2026 00:00:00 +0000

This guide takes an administrator from a running Scipio 4.0 server to a working agent connection in five steps. It covers Claude Code, Claude Desktop, Cursor, VS Code, and any other client that speaks MCP over Streamable HTTP.

1. Check the server#

Open https://<host>/admin/control/McpServers as an administrator. The page lists every MCP server profile and its tools. Each application has its own endpoint: /ordermgr/mcp, /accounting/mcp, /cms/mcp, /shop/mcp, and so on. The hub is /admin/mcp.
Confirm the server runs behind HTTPS. A plain HTTP request is refused unless mcp.allowInsecure=true in framework/mcp/config/mcp.properties (development only).
When a reverse proxy terminates TLS, set mcp.trustedProxies to the proxy addresses. Only those addresses may assert X-Forwarded-Proto: https.

2. Create a user for the agent#

The seed user scp-agent (group SCIPIO_AGENT) exists after the seed data load. It has read access to every back-office application and no write permission.
For an agent that must write, create a dedicated user login and put it in a security group with the needed <APP>_UPDATE permissions, plus MCP_ACCESS, MCP_GATEWAY and OFBTOOLS_VIEW. Grant MCP_CODE_WRITE only when the agent must edit CMS templates or scripts.
Never give an agent the system or admin login. Tokens for system are refused.

3. Create a token#

Open https://<host>/admin/control/McpTokens.
Fill in the user login, a token name, the webapps the token may use (* for all), the read-only flag, the expiry (default 90 days, maximum 365) and, for a shop token, a spend cap (maxOrderAmount).
Click “Create Token”. Copy the token now. The page shows it once, together with ready-made connection snippets that already contain the token.

4. Connect the client#

Open https://<host>/admin/control/McpSkills. It shows the hub endpoint and one snippet per client. Replace <token> with the token from step 3.

Agent access security

Tue, 08 Sep 2026 00:00:00 +0000

This page describes how Scipio 4.0 secures agent access through MCP, and what an operator must do before and during production use. Read Agent quickstart for the setup steps.

Principles#

A token is a user login. An agent has exactly the permissions of that user. No permission comes from the token itself.
Default deny. A call passes only when every gate in the policy engine allows it.
One rule for every endpoint. The hub and the application endpoints apply the same policy.
Everything is audited. Every tool call, denied or not, writes one McpAuditLog row.
Executable code is a separate permission. CMS templates and scripts need MCP_CODE_WRITE.

Permissions and groups#

Permission	Grants
`MCP_ACCESS`	Use any MCP endpoint. Required for every token user.
`MCP_GATEWAY`	Call any service through `scipio_service` with `action` `call` (still subject to the policy engine).
`MCP_ENTITY_READ`	Read entities outside a server’s allowlist through `scipio_entity` with `action` `find`.
`MANUFACTURING_FLOOR`	Declare, scan, start and complete production run tasks without `MANUFACTURING_UPDATE`.
`MCP_MAIL_SEND`	Send a mail from a template through `mail_send_template`. Granted to `FULLADMIN`.
`MCP_ENTITY_WRITE`	Write entities through the entity tools (also needs `ENTITY_MAINT`).
`MCP_ADMIN`	Manage tokens of any user, view the audit log, reload the registry, run services of components without a webapp.
`MCP_CODE_WRITE`	Write CMS FreeMarker templates, Groovy scripts and asset templates. Remote code execution by design.

Seed groups:

Extending agent access

Tue, 08 Sep 2026 00:00:00 +0000

This page shows how to extend framework/mcp: a tool, a service tool, a server profile, a provider, a skill, a path handler, a permission, and how to smoke-test a change with curl. Read framework/resources/templates/mcp/README.txt first for the starter files.

1. Add a tool#

A tool is one static method on a class an @McpServer annotation already covers. Add a public static method under your component’s src/.../mcp/ package; the first parameter is always McpCallContext ctx, each other parameter carries an @McpParam with an explicit name. Annotate the method with @McpTool: a topic, a name in snake_case, a short description, readOnly = true when the tool only reads data. The topic is the tool the agent sees; the name is the action it passes. Every method that names the same topic joins the same tool, which is why one application shows an agent five tools and not fifty. Return a Map, a List, a GenericValue, a String, or an McpResult; convert a raw service result with ResultConverter.toJsonMap(result). Throw McpToolException for a tool error, or McpToolException.denied(msg) for a permission denial.

Agent tools reference

Thu, 17 Sep 2026 00:00:00 +0000

Every application answers POST /<webapp>/mcp. A tool is one business object; the action argument selects what to do with it. An action marked with * writes data and needs the update permission of the application; the others read. The six core tools (scipio_whoami, scipio_apps, scipio_service, scipio_entity, scipio_document, scipio_admin) exist on every endpoint. Call a tool with {"action": "find", ...}; the schema of each action is in tools/list.

This page is generated from the @McpServer classes in the source tree.