QPR ProcessAnalyzer as MCP Server

QPR ProcessAnalyzer can act as a Model Context Protocol (MCP) server, allowing external tools and applications to interact with its analysis capabilities through script-based tools.

Overview of MCP Server Functionality

The Model Context Protocol (MCP) is a standard for communication between modeling tools. By acting as an MCP server, QPR ProcessAnalyzer exposes its functionalities, which are implemented as scripts, to any MCP-compliant client. This enables a wide range of integrations and automation possibilities.

Key features:

• Script-based Tools: Any QPR ProcessAnalyzer script can be exposed as an MCP tool.
• Flexible Authentication: Supports both API Key and OAuth 2.0 for secure access.
• Standardized Communication: Uses the MCP standard for interoperability with clients like MCP Inspector and Visual Studio Code.

Configuring the MCP Server

To enable and configure the MCP server functionality in QPR ProcessAnalyzer, a system administrator needs to adjust the McpServerConfiguration setting in the PA Configuration Database Table.

Authentication Methods

The supported methods to authenticate MCP clients are OAuth 2.0 or API key. Both the authentication methods can be configured at the same time to use both.

OAuth 2.0 Authentication

This method provides per-user authentication, allowing each MCP request to be authenticated against a specific QPR ProcessAnalyzer user. This is the recommended authentication method for MCP. To use OAuth 2.0 Authentication, set the BuiltInOAuthServerConfiguration value in the PA_CONFIGURATION database table with at least an AcceptedAudiences value other than the default.

Setting up IIS to support OpenId Connect Discovery

Some clients use the OpenID Connect discovery metadata to be available from the standard endpoint: /.well-known/openid-configuration. To get this endpoint working when QPR ProcessAnalyzer is hosted in Windows in IIS, the following setup is required:

Add an IIS rewrite rule and a CORS header at the IIS root-level web.config. Adding rewrite rules to IIS requires URL Rewrite to be installed on the system.

1. Open the root-level IIS web.config.

2. Add the following configuration under <system.webServer>:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Redirect OIDC Discovery - openid-configuration" stopProcessing="true">
          <match url="^\.well-known/openid-configuration$" />
          <action type="Redirect"
                  url="<QPR ProcessAnalyzer Path>/builtin-oauth/.well-known/openid-configuration"
                  redirectType="Permanent" />
        </rule>
      </rules>
    </rewrite>
	
    <httpProtocol>
      <customHeaders>
        <add name="Access-Control-Allow-Origin" value="<Allowed CORS origins>" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

3. Replace placeholders:

• <QPR ProcessAnalyzer Path>: IIS virtual path to the installed QPR ProcessAnalyzer application, for example qprpa.
• <Allowed CORS origins>: CORS origin origin(s) allowed to call discovery. Use specific origin(s) in production.

You may also need to add the URL of the client accessing the MCP server to the CorsOrigins setting in the server's appsettings.json.

After configuration, the following URL should return OpenID provider metadata:

https://<your-host>/.well-known/openid-configuration

If the endpoint does not work, verify that the rewrite rule is in the IIS root-level web.config and that the target path resolves to .../builtin-oauth/.well-known/openid-configuration.

API Key Authentication

This method uses a static, pre-shared key for all MCP requests. To use API key authentication:

• Set the McpApiKey value in the McpServerConfiguration setting in the PA_Configuration database table. The MCP client must then include this key in the X-Mcp-Api-Key header of each request.
• Create a user named "MCP Client" in QPR ProcessAnalyzer. All the MCP server operations are performed in the context of "MCP Client" user, i.e. the user can't see or modify anything the "MCP Client" user can't see or modify in any other way.

Creating MCP Tools

MCP tools are implemented using scripts written in QPR ProcessAnalyzer expression language. A script will be added as the MCP tool when the MCP tool checkbox is enabled in the Script Properties. Only system administrator users can enable the MCP tool checkbox. Also, scripts that are MCP tools, only system administrators can modify them because any changes to the MCP interface is restricted to system administrators for security reasons.

To enable a script as an MCP Tool:

1. Log in to QPR ProcessAnalyzer as a System Administrator.
2. Open or create the script.
3. For the script to be used as an MCP tool, give it a name. This name is then used as the MCP tool name. It is important to ensure that every script intended for MCP use has a non-empty, valid name, as clients may fail to discover tools with invalid names.
4. Open the properties of the script.
5. Switch to the MCP tab and select the MCP tool checkbox.
6. Switch to the Description tab and provide a description. The description is added to the context of the client.

MCP Tool Configuration

Every script can define its own McpTool configuration as JSON. Supported values are same as here, except for the name which is always generated automatically and can't be overridden. Defining the McpTool configuration will override any default configurations generated for scripts automatically by QPR ProcessAnalyzer. For example, specifying the value for "title" here will override the default functionality of using script's name as title of the tool.
Example: The following JSON configures the MCP tool with a customized title and description, as well as some additional MCP tool annotations:

{
    "title": "Example MCP tool title",
    "description": "Example MCP tool description",
    "annotations": {
        "destructiveHint": true,
        "idempotentHint": true,
        "openWorldHint": true,
        "readOnlyHint": false
    }
}

Defining Input Parameters

MCP tool input parameters are defined using a JSON schema following the Model Context Protocol's JSON Schema. Each supported input parameter is listed under properties. By default, script don't enforce any schema.

Example: The following schema defines a script with five different types of parameters:

{
  "type": "object",
  "properties": {
    "stringParameter": {
      "type": "string",
      "description": "String parameter"
    },
	"numberParameter": {
	  "type": "number",
	  "description": "Number parameter"
	},
	"booleanParameter": {
	  "type": "boolean",
	  "description": "Boolean parameter"
	},
	"arrayParameter": {
	  "type": "array",
	  "description": "Array parameter",
	  "nullable": true,
	  "items": {
		  "type": "integer"
	  }
	},
	"objectParameter": {
	  "type": "object",
	  "description": "Object parameter",
	  "properties": {
	    "inner": {"type": "string"}
	  }
	}
  }
}

After this, the tool can be called, for example, with the following set of parameters:

{
  "stringParameter": "bar",
  "numberParameter": 123.456,
  "booleanParameter": true,
  "arrayParameter": [ 1, 2, 3 ],
  "objectParameter": { "inner": "test" }
}

Defining Structured Tool Output

Structured tool output is described using a JSON schema following the Model Context Protocol's JSON Schema. By default, scripts don't enforce any schema and the result is considered to be just text.
Example: The following example configures the script's return value to contain an object having five different types of properties.:

{
    "type": "object",
    "properties": {
    "string": {
        "type": "string",
        "description": "String parameter"
    },
    "number": {
        "type": "number",
        "description": "Number parameter"
    },
    "boolean": {
        "type": "boolean",
        "description": "Boolean parameter"
    },
    "array": {
        "type": "array",
        "description": "Array parameter",
        "nullable": true,
        "items": {
            "type": "integer"
        }
    },
    "object": {
        "type": "object",
        "description": "Object parameter",
        "properties": {
        "inner": {"type": "string"}
        }
    }
    }
}

Testing MCP tools in QPR ProcessAnalyzer

When developing MCP tools, it might be useful try test them in QPR ProcessAnalyzer before publishing as MCP tools. Scripts (used as MCP tools) can be called in the Expression Designer. The following example expression calls a script with some parameters and shows the return value as json:

let returnValue = ScriptById(1).Run(#{
  "string_param": "value1",
  "integer_param": 123,
  "boolean_param": false,
  "array_param": ["a", "b", "c"]
});
return ToJson(returnValue);

Connecting as an MCP Client

MCP clients can connect to the QPR ProcessAnalyzer server to discover and execute the available tools. The endpoint and connection details are:

• URL: The primary MCP endpoint is located at /api/mcp relative to the QPR ProcessAnalyzer server URL (e.g., https://your-pa-server.com/qprpa/api/mcp).
• Type: http.
• Headers: Clients must include the following headers in their requests:
  • X-Mcp-Api-Key: Used when authenticating with API key. The API key that is defined in the McpServerConfiguration setting in the PA_CONFIGURATION database table.
• Client ID: Used when authenticating with OAuth 2.0. If the AcceptedAudiences value in the BuiltInOAuthServerConfiguration setting in the PA_CONFIGURATION database table is something else than null, the client ID has to match it. If the AcceptedAudiences value is null, the client ID must be created with Dynamic Client Registration Protocol (DCR). This is often automatically done by MCP Client software.

Example: Using MCP Inspector

MCP Inspector is a standard client that can be used to test the connection and interact with the MCP tools.

• Connect to Server:
  • In MCP Inspector, provide the server's MCP endpoint URL (e.g., https://your-pa-server/qprpa/api/mcp)
  • Select Streamable HTTP as the transport type.
  • Select "Via Proxy" as connection type.
• Authenticate:
  • If using API Key-based authentication, configure "X-Mcp-Api-Key" as additional custom header with the value specified in the McpServerConfiguration setting of the PA server.
  • If using OAuth, set one of the accepted audience values to Authentication/OAuth 2.0 Flow/Client ID (or leave it empty if DCR is enabled).
    • Open Auth Settings
    • Click "Quick OAuth Flow"-button.
      • Perform OAuth authorization using the built-in OAuth provider.
      • Provided that the authentication has been configured correctly, a successful authentication message should be shown.
  • Click Connect.
• List and Call Tools: Once connected, you can list the available tools and call them. For example, to call a tool created for a parameterless QPR ProcessAnalyzer script having id 216, the client would send a JSON-RPC request like the one below:

{
  "method": "tools/call",
  "params": {
    "name": "Script-216",
    "arguments": {},
    "_meta": {
      "progressToken": 0
    }
  }
}