Create MCP Tools

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 option is selected in the Script Properties. Only system administrator users can enable the MCP tool option. Also, only system administrators can modify scripts that are MCP tools, 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. The maximum length of the name is 50 characters.
4. Open the properties of the script.
5. Switch to the MCP tab and select the MCP tool option.
6. Switch to the Description tab and provide a description. The description is added to the context of the client.

MCP Tool Settings

MCP Tool Description

The tool description is a concise metadata field that tells an AI agent what a tool does and when it should be used. It serves as the primary signal during the agent's planning and routing phase, where the agent decides which tool (if any) to call in response to a user's request. The tool description answers two questions for the agent:

• What does this tool do? – A brief explanation of the tool's capability.
• When should the agent use it? – The conditions, scenarios, or trigger signals that indicate this tool is the right choice.

It does not need to explain how to format inputs or how to interpret outputs — those concerns belong to the input parameter descriptions and output schema descriptions, respectively. During planning, agents load all available tool descriptions into their context simultaneously to evaluate which tool best fits the task. This means:

• Every character in every description costs tokens – across all tools, not just the one ultimately selected.
• Long descriptions risk truncation – some implementations silently cut off descriptions beyond 1000–2000 characters, potentially hiding critical information.
• Agents perform better with clear, concise signals – verbose descriptions introduce noise that can confuse tool selection.

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": "hello",
  "numberParameter": 123.456,
  "booleanParameter": true,
  "arrayParameter": [ 1, 2, 3 ],
  "objectParameter": { "inner": "test" }
}

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. Due to the limitations of MCP protocol, if defined, the top-level object type should be "object".

Example: The following example configures the script's return value to contain an object having the "models" property with information about each model:

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

MCP Tool Metadata

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.

Following annotations are available to indicate about the MCP tool:

• destructiveHint: MCP tool call deletes data which might be permanently lost. Some LLM agents ask for confirmation from the user, to make sure that destructive tool calls are not made by mistake.
• idempotentHint: All MCP tool calls with the same parameters always provide the same result. Some LLM agents may cache tool call results for idempotent MCP tools to improve performance and reduce load from the MCP server.
• openWorldHint: MCP tool call in the MCP server will use some external services. Open world tool calls are expected to be slower than other tool calls.
• readOnlyHint: MCP tool call does not change any data, and thus the call may not have any potentially undesired effects. Some LLM agents ask for confirmation from the user, to make sure that tool calls that change data are not made by mistake.

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",
    "annotations": {
        "destructiveHint": true,
        "idempotentHint": true,
        "openWorldHint": true,
        "readOnlyHint": false
    }
}

MCP Icons

The MCP tools, prompts, and resources can have icons for visual identification in client user interfaces. Icons are defined in the icons array property in the entity's MCP configuration.

The icon object has the following properties:

• src (required): URI pointing to the icon resource. Can be an HTTP/HTTPS URL pointing to an image file. Can be a data URI with base64-encoded image data (e.g. data:image/png;base64,...).
• mimeType (optional): MIME type of the icon image. Supported values include:
  • image/png: PNG images.
  • image/jpeg or image/jpg: JPEG images.
  • image/svg+xml: SVG images (scalable, but requires security precautions against embedded scripts).
  • image/webp: WebP images.
• sizes (optional): Array of size specifications at which the icon can be used. Examples: ["48x48"], ["96x96", "48x48"], ["any"] for scalable formats like SVG. If not provided, clients should assume the icon can be used at any size.
• theme (optional): Specifies the theme the icon is designed for. If not provided, clients should assume the icon can be used with any theme.
  • light: icon designed for use on a light background.
  • dark: icon designed for use on a dark background.

Example: The following JSON configures the MCP entity to have an icon for both light and dark themes:

{
  "icons": [
    {
      "src": "https://example.com/icons/tool.png",
      "mimeType": "image/png",
      "sizes": ["48x48"],
      "theme": "light"
    },
    {
      "src": "https://example.com/icons/tool-dark.svg",
      "mimeType": "image/svg+xml",
      "sizes": ["any"],
      "theme": "dark"
    }
  ]
}

Testing MCP tools using 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(#{
  "stringParameter": "hello",
  "numberParameter": 123.456,
  "booleanParameter": true,
  "arrayParameter": [1, 2, 3]
  "objectParameter": {
    "inner": "test"
  }
});
return ToJson(returnValue);

Now, if script having id 1 has the following script source code:

#{
  "string": stringParameter,
  "number": numberParameter,
  "boolean": booleanParameter,
  "array": arrayParameter,
  "object": objectParameter
}

and is configured as specified in the previous chapter, the result of expression will be the following valid JSON object as string:

{
  "string": "hello",
  "number": 123.456,
  "boolean": true,
  "array": [1,2,3],
  "object": {"inner": "text"}
}