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 Keys. It's also possible 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 McpApiKey value in the McpServerConfiguration setting in the PA_CONFIGURATION database table as null.
• 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

When QPR ProcessAnalyzer is hosted in IIS, some clients (for example MCP Inspector) may expect OpenID Connect discovery metadata to be available from the standard endpoint:
/.well-known/openid-configuration

To make this work, 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.

Oauth 2.0 and API Key Authentication

This method combines both per-user authentication and static API key authentication. To use both OAuth 2.0 and API key Authentication:

• Set the McpApiKey value in the McpServerConfiguration setting in the PA_Configuration database table. The MCP client using API key authentication 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.
• Set the BuiltInOAuthServerConfiguration value in the PA_Configuration database table with at least an AcceptedAudiences value other than the default.

Implementing MCP Tools with Scripts

Any QPR ProcessAnalyzer script can be turned into an MCP tool. This is controlled in the Script Properties.

To enable a script as an MCP Tool:

1. Log in to QPR ProcessAnalyzer as a System Administrator.
2. 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.
3. Open the properties of the script.
4. Switch to the MCP tab and select the MCP tool checkbox.
5. Switch to the Description tab and provide a description. The description is added to the context of the client.

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
    }
  }
}