Overview

Oryon is an automation tool for Java UI applications (for example Syrius FX/Swing clients) that lets users record and replay interaction scenarios against fat-client applications. The generated scripts can be customised in Groovy to support more advanced automation needs, covering use cases that range from functional testing and load & performance testing to synthetic monitoring and robotic process automation (RPA).

The Oryon MCP Server exposes those capabilities to AI assistants and coding agents through the Model Context Protocol (MCP). From their own environment, in plain text, they can inspect and drive a running Java UI application and resolve robust XPaths into Oryon automation scripts, as an alternative or a complement to the Oryon IDE.

The tools exposed by Oryon MCP let an AI agent connect to a running application, inspect its UI, interact with it, and run Groovy scripts against it. A detailed list of all available tools can be found under Tools.

Installation

Two Java processes are involved, set up as two distinct jobs: the Oryon MCP Server, and the target application client, with the Oryon agent loaded into its JVM. Running the Oryon IDE alongside would add a third. You start the application under test with the Oryon agent attached to it; your MCP client starts the MCP server, which then attaches to that agent.

Prerequisites

Before using the Oryon MCP Server, ensure you have:

• The Oryon distribution, which contains both the agent (agent/oryon-agent.jar) and the MCP server (mcp/oryon-mcp.jar)
• A valid Oryon license file. Note that both the agent and the MCP server require licenses, but the same license file can usually be used for both.
• A JDK, Java 17 to 21, with 21 recommended. A single Java 21 build for everything is the simplest choice: take a JavaFX one (for example Azul Zulu 21 FX) if the application under test uses JavaFX, or if you also run the Oryon IDE.
• An MCP-compatible client:
  • Claude Code
  • Claude Desktop
  • VS Code
  • Any MCP-compatible client

Start the application under test

Start the application under test yourself: the MCP server runs in attach mode and never starts it. Attach the Oryon agent to it, with the module that matches the UI toolkit (Swing, the Syrius module, and so on). Give the full path to a Java binary here too, so that the application runs on a version the agent supports:

On Windows:

C:/jdk21/bin/java.exe -javaagent:C:/oryon/agent/oryon-agent.jar=module:Swing,license:C:/oryon/license/oryon.license -jar your-application.jar

On macOS and Linux:

/path/to/jdk21/bin/java \
  -javaagent:agent/oryon-agent.jar=module:Swing,license:license/oryon.license \
  -jar <your-application>.jar

Agent arguments are comma-separated key:value pairs, and both module and license are mandatory. See Oryon Agent for the full description of these options.

The application console then reports the Oryon agent listening:

Starting server socket on port 12121

To use another port, set -DoryonAgentPort=<port> on the application’s JVM and match it with ORYON_MCP_PORT below.

Client setup

Register the server in your MCP client. The defaults target an Oryon agent on localhost:12121, so a standard local setup needs no environment variables.

Pass the path to the license file as the argument after the JAR, as in the examples below. Alternatively, omit the argument and specify the license file in the ORYON_MCP_LICENSE environment variable; if both are present, the argument takes precedence. Without a valid license, the server reports the problem on stderr and exits, so your MCP client shows a failure.

Give the full path to the Java 21 binary rather than a bare java. The client runs command directly: it does not consult JAVA_HOME, and a client launched from the desktop does not inherit your shell’s PATH, so java there can resolve to a different JDK than the one your terminal reports, and outside the supported range.

The examples below use macOS and Linux paths. On Windows, write these paths in Windows form (but favor slashes over backslashes for directory separators), for example C:/jdk21/bin/java.exe, C:/oryon/mcp/oryon-mcp.jar and C:/oryon/license/oryon.license.

Claude Code

claude mcp add oryon -- /path/to/jdk21/bin/java -jar /path/to/oryon/mcp/oryon-mcp.jar /path/to/oryon/license/oryon.license

Claude Desktop

{
  "mcpServers": {
    "oryon": {
      "command": "/path/to/jdk21/bin/java",
      "args": ["-jar", "/path/to/oryon/mcp/oryon-mcp.jar", "/path/to/oryon/license/oryon.license"]
    }
  }
}

VS Code

code --add-mcp '{"name":"oryon","command":"/path/to/jdk21/bin/java","args":["-jar","/path/to/oryon/mcp/oryon-mcp.jar","/path/to/oryon/license/oryon.license"]}'

Other MCP clients

Any client that supports stdio MCP servers can run the same command: the Java 21 binary, with -jar oryon-mcp.jar, and the path to the license file provided using a command argument or an environment variable.

Verify your setup

After saving the configuration, reload or restart your MCP client: MCP servers are loaded at session startup.

From the terminal, if your client offers one. In Claude Code:

claude mcp list

oryon should appear with status connected.

In your AI agent, confirm the tools are available and that the server reached the application:

What Oryon tools do you have? Check the connection status.

You should see the oryon_* tools listed, described under Tools, and oryon_status reporting the connection as ready, along with the Oryon agent module in use.

If the server is up but the tools report that they are not connected, the MCP side is healthy and the Oryon side needs attention: the application is not running, it is listening on another port, or its license or module was rejected. Start the application and call oryon_connect. This is also how you recover from a crash, without restarting your MCP client.

Configuration

All settings are optional. Set them as environment variables in the env block of the MCP server entry, in your client’s configuration file.

For example, to reach an agent listening on port 9999:

{
  "mcpServers": {
    "oryon": {
      "command": "/path/to/jdk21/bin/java",
      "args": ["-jar", "/path/to/oryon/mcp/oryon-mcp.jar"],
      "env": { "ORYON_MCP_PORT": "9999", "ORYON_MCP_LICENSE": "/path/to/oryon/license/oryon.license" }
    }
  }
}

Next steps

With the server connected, the Tutorial walks through automating a Java application end to end, and Tools describes everything the server exposes.