Version: Next

Flow Controller MCP

The jf-addon-mcp addon exposes jadice flow controller job and system state to Model Context Protocol (MCP) clients, such as Claude Desktop or Claude Code, ChatGPT, OpenCode, ... It runs embedded inside the controller, using the raw MCP Java SDK (io.modelcontextprotocol.sdk:mcp-core) over a streamable-HTTP transport - no separate process is required.

The addon is present in jf-controller by default but disabled unless explicitly enabled via configuration. Additionally, your jadice flow license must be eligable for MCP usage.

Configuration

All properties live under jadice-flow.addons.mcp in application.yaml.

Property	Type	Default	Description
`enabled`	boolean	`false`	Master switch for the addon. When `false`, no MCP beans are created and the endpoint is not routable.
`server-name`	string	`jadice-flow-controller`	Name reported to MCP clients as part of the server's implementation info.
`server-version`	string	`1.0.0`	Version reported to MCP clients as part of the server's implementation info.
`instructions`	string	`Query jadice flow controller job and system state.`	Instructions shown to MCP clients describing how to use this server.
`endpoint`	string	`/mcp`	The path the MCP streamable-HTTP endpoint is mounted at. Subject to the same Spring Security filter chain (`security.mode`) as the rest of the controller's REST endpoints - it is not special-cased to be open.
`job-template-backup-prefix`	string	`_bak-`	Prefix used by `write-saveJobTemplate` to name the backup copy it creates of a job template before overwriting an existing one (backup name = prefix + original `jobName`).
`allowed-tools`	list of regex strings	`[".*"]`	Whitelist of regex patterns (Java `String.matches`, full match) checked against each tool's registered name. A tool is only registered with the MCP server if its name matches at least one pattern. Mutating tools are named with a `write-` prefix (see below), so this can be used to expose only read-only tools, only writes, or an explicit subset.

Config example

jadice-flow:
  addons:
    mcp:
      enabled: true
      server-name: jadice-flow-controller
      server-version: 1.0.0
      instructions: "Query jadice flow controller job and system state."
      endpoint: /mcp
      job-template-backup-prefix: "_bak-"
      allowed-tools:
        - ".*"

To restrict the exposed tool set, adjust allowed-tools, for example:

      # Read-only: exclude every tool prefixed with "write-"
      allowed-tools:
        - "^(?!write-).*$"

      # Writes only
      allowed-tools:
        - "write-.*"

Available tools

All tools below share the naming convention that mutating tools are prefixed with write-; every other tool is read-only. This lets allowed-tools filter by capability class without listing every tool name individually.

Tool	Read/write	Description
`listJobs`	read	Returns a list of executed or running jobs. Takes a job template name filter (`%` for all) and an optional page size.
`getJobDetails`	read	Returns details for a job by ID. Job properties are always included; audit information is opt-in via `includeAuditInfo` (can be large - tens of KB even for a single job).
`showWorkerClusterInfo`	read	Shows info about currently registered and running jadice flow worker instances.
`getItemsOfJob`	read	Returns the items of a job.
`getItemByID`	read	Returns an item by its unique ID.
`getResultPartsOfJob`	read	Returns the resulting parts of a job (`BASE_PART`, not `META`) after all steps were processed. Only useful on successful jobs.
`listJobTemplateNames`	read	Returns the names of all currently registered job templates.
`getJobTemplateByName`	read	Returns the full JSON representation of a registered job template by name.
`listWorkerDefinitions`	read	Returns all currently registered worker definitions. A worker definition is referenced by name in a job template step.
`getWorkerDefinition`	read	Returns a single registered worker definition by name.
`getFlowSystemStatus`	read	Shows the current general system state and how many jobs are currently running.
`getSystemConfig`	read	Shows the current system configuration (e.g. maximum parallel job executions).
`write-createJob`	write	Creates and starts a new job from an existing job template and one or more document parts already present in storage. Does not accept file content - only existing storage URLs (e.g. from `getResultPartsOfJob`/`getItemsOfJob`, or a URL from a prior manual upload). Useful for reprocessing: reuse a finished job's result-part URL as input to a new job.
`write-saveJobTemplate`	write	Creates a new job template, or modifies an existing one (upsert by `jobName`). Before overwriting an existing template, its previous version is automatically backed up under a `job-template-backup-prefix`-prefixed name with `enabled: false`, so it can be restored later via `getJobTemplateByName` + `write-saveJobTemplate`.

Why no file upload

write-createJob intentionally does not accept file content directly. MCP tool calls have a practical size ceiling (commonly around 25k tokens for a tool call/response in current clients), and base64-encoding inflates payload size by about a third - well below what's needed for real production documents (scans, PDFs, emails typically run hundreds of KB to several MB). Instead, provide a storage URL that already exists (from a prior manual upload, or from another job's result parts).

Usage

Add the controller as an MCP server to Claude Code:

claude mcp add --transport http jadice-flow-controller http://localhost:8080/mcp

For the Claude Desktop app, add the server to claude_desktop_config.json (via Settings > Developer > Edit Config), bridging streamable-HTTP through mcp-remote since direct remote-URL entries aren't reliably supported there:

{
  "mcpServers": {
    "jadice-flow-controller": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

Fully restart the client application afterwards - MCP clients typically fetch the tool list once per connection, so a server restart alone (e.g. after changing allowed-tools) is not picked up until the client reconnects too.

Security

The MCP endpoint inherits the same Spring Security filter chain (security.mode: none/basic/oauth) as the rest of the controller's REST endpoints - it is not exposed with weaker defaults. Since the read tools expose job metadata, item/part content references, worker topology and system configuration, and the write tools can create jobs and modify job templates, treat this endpoint under the same access-control expectations as the underlying job/** and admin/** REST APIs when enabling it on a network-reachable instance.

Configuration​

Config example​

Available tools​

Why no file upload​

Usage​

Security​