Enable AI-powered industrial automation through Model Context Protocol integration.

Overview

The

AI Runtime service bridges FrameworX solutions with AI language models, enabling intelligent automation assistance while maintaining industrial-grade safety

. This connector exposes your solution's live data and functionality as structured tools that AI models can invoke

.

Note: This connector is for querying live data from running solutions (connects to TServer.exe). For AI-assisted solution configuration, see AI Designer Connector.

Key Capabilities

• Real-time Data Access — Query live tag values, historian data, and alarm states through AI

• Unified Namespace Browsing — Explore your tag structure and discover available data
• Historical Analysis — Query historian for trend analysis and past behavior investigation
• Alarm Monitoring — Check active alarms and query alarm history
• Custom Methods — Extend with your own solution-specific AI tools
• Platform Agnostic — Works with Claude, GitHub Copilot, and other MCP-compatible AI models

Integration Architecture

This diagram shows an AI model (such as Claude or GPT) communicating with a FrameworX solution through the MCP Protocol, which acts as a standardized bridge for exchanging context and invoking tools. FrameworX then exposes structured methods that the model can call to access tag data, query historical records, monitor alarms, and run custom operations.

When to Use AI Runtime

Why Custom Tools Matter

Some platforms may offer only built-in MCP tools that let AI read or write tags, or run queries, or perform specific tasks in the platform. In practice, this approach has limited value:

• Real solutions have hundreds of equipment items and thousands of tags
• Operators don't memorize tag names and their needs goes beyond plain data, it requires context, aggregation, and analysis
• Open access to running systems creates safety concerns and privacy issues
• LLM hallucination risk makes direct control inappropriate

FrameworX approach: Custom Runtime Tools

Because FrameworX compiles .NET code at runtime, you can create domain-specific tools that expose exactly what you want, with descriptions that guide AI to correct usage. External applications query at the semantic level: "get tank levels" instead of "read Tag.Area1.Tank3.LT001.PV".

This gated access model means:

Prerequisites

• FrameworX 10.1 or later
• Cross-platform .NET Desktop Runtime matching your FrameworX version: .NET 8 for 10.1.4 and earlier, .NET 10 for 10.1.5 and later
• Claude Desktop or compatible MCP client
• Running FrameworX solution (TServer.exe)
• Network connectivity

Configuration

The MCP Server starts automatically when your solution runs. You need to configure your AI client to have the solution connector.

Connection Methods

Local Access: stdio Configuration

Use stdio when the AI client runs on the same machine as your FrameworX solution.

Step 1 — Open the Claude configuration folder

Press Win + R, type %APPDATA%\Claude, and press Enter.

Step 2 — Edit claude_desktop_config.json

Open the file and add the following configuration. Adjust the runtime folder in the path to match your FrameworX version (net8.0 for 10.1.4 and earlier, net10.0 for 10.1.5 and later):

{
  "mcpServers": {
    "MCPRuntime": {
      "command": "C:\\Program Files\\Tatsoft\\FrameworX\\fx-10\\net8.0\\RuntimeMCP.exe",
      "args": ["/host:127.0.0.1", "/port:3101"],
      "transport": "stdio"
    }
  }
}

Remote Access: HTTP Configuration

Use HTTP mode when the AI client runs on a different machine from the FrameworX solution.

Server Setup

1. (Optional) Configure server settings

If you need to change the port, set an API key, or configure TLS, edit this file before starting the server:

C:\Users\Public\Documents\FrameworX\MachineSettings\RuntimeMCPHttp.json

HTTP Settings Reference:

{
  "appSettings": {
    "X_API_KEY": "",
    "CertFileName": "",
    "CertPass": "",
    "CertHash": "",
    "ListenPort": "10120",
    "Runtime": {
      "Host": "localhost",
      "Port": "3101",
      "Username": "guest",
      "Password": ""
    }
  }
}

2. Start the HTTP server

Run "C:\Users\<user>\Documents\FrameworX\Utilities\StartRuntimeMCPHttp.bat" on the machine where your FrameworX solution is running.

Client Setup

Replace <RemoteIP> with the IP address or hostname of the server machine.

GitHub Copilot (.mcp.json)

{
  "servers": {
    "FrameworX Runtime": {
      "type": "http",
      "url": "http://<RemoteIP>:10120",
      "headers": {
        "X-API-KEY": "<your-api-key>"
      }
    }
  }
}

Claude Desktop / Claude.ai (.mcp.json)

{
  "mcpServers": {
    "FrameworX Runtime": {
      "command": "C:\\WINDOWS\\System32\\cmd.exe",
      "args": [
        "/C",
        "C:\\Program Files\\nodejs\\npx.cmd",
        "-y",
        "mcp-remote",
        "http://<RemoteIP>:10120/mcp",
        "--allow-http"
      ]
    }
  }
}

Multiple Connections: To connect to multiple runtimes, use /instance:<number> argument and matching numbered settings (e.g., X_API_KEY2, ListenPort2, Runtime2).

Verifying Connection

1. Click the LLM connector icon — you should see your solution name
2. Go to Settings → Developer and verify the connection shows "running"
3. Ask the AI a simple question like "What is the server uptime?"

Available Tools

AI Runtime provides 11 built-in platform tools plus solution-authored custom tools, organized by category. Each category is gated independently in Solution Settings → Data Servers → MCP for Runtime; the Info tools (runtime_connect, runtime_describe_binding) are gated only by the master toggle so AI clients can bootstrap and verify the target before any sub-category is enabled.

Info (2 tools)

UNS Tools (5 tools, gate: Enable UNS Tools)

Tools for querying live data and structure from the runtime Object Model — the 12-root hierarchy that includes the Unified Namespace (Tag.*) plus the built-in namespaces (Server, Client, Alarm, Device, Historian, Dataset, Script, Display, Security, Report, Info).

Alarm Tools (2 tools, gate: Enable Alarm Tools)

Dedicated alarm-query tools that hit the alarm subsystem's state machine and historian. Reading an Alarm.* namespace value through runtime_get_value, or reading a tag's current alarm-state through runtime_describe_object, stays under UNS Tools — those are UNS data reads, not dedicated alarm queries.

Historian Tools (2 tools, gate: Enable Historian Tools)

Tools for querying historical time-series data.

Custom Tools (gate: Enable Custom Tools)

Solution-authored {{\[McpServerTool\]}} methods on Scripts ? Classes of type *MCP Tool*. See the Custom Methods section below for authoring guidance.

Reading Live Values (runtime_get_value):

• "What is the current value of Tag.Temperature1?"
• "Get the value of Tag.Plant1/Line2/Pressure"
• "What is the Server.SystemMonitor.CPUUsage?"
• "How many active alarms are there?" (uses Alarm.TotalCount)

Browsing the Object Model (runtime_browse_object_model):

• "What tags are available under Tag.Plant1?"
• "Show me the members of Tag.Pump1" (for UserType tags)
• "What alarm groups exist?"
• "Browse the Server namespace"

Searching the UNS (runtime_search_uns):

• "Find all tags containing 'Temperature'"
• "Search for UserTypes related to 'motor'"
• "Find anything with 'pump' in the description or labels"

Historical Analysis (runtime_get_tag_history):

• "Show me the temperature history for today"
• "Get the historian data for Tag.Pressure from 8am to noon"
• "What was the highest temperature value today and when did it occur?"

Active Alarms (runtime_get_active_alarms):

• "Are there any active alarms?"
• "What alarms are currently in alarm state?"
• "Show me all unacknowledged alarms"

Alarm History (runtime_query_alarm_history):

• "Show me alarms from the last 24 hours"
• "How many alarms were acknowledged today?"
• "Query the alarm history for Tag.Temperature1"
• "What alarms occurred during the night shift?"

Custom Methods

You can extend the MCP server with your own solution-specific tools by creating custom methods in Scripts.

Tool names in runtime: When naming your runtime tools, it's strongly recommended that you keep the pattern runtime_<toolName>. When AI is also running AI Designer, or other third-party tools, that helps to correctly identify the right tool to use. For adherence with MCP standards use snake_case for method names (e.g., runtime_get_tank_level), instead of RuntimeGetTankLevel that would be a typical C# convention.

Creating Custom Methods

1. Navigate to Scripts → Classes
2. Create a new class with type MCP Tool
3. Define methods using MCP decorators:

[McpServerTool, Description("Get current tank level for a specific tank")]
public string runtime_get_tank_level(
    [Description("Tank identifier (1-4)")] string tank_id = "1")
{
    return @Tag[$"Tank{tank_id}_Level"].ToString();
}

Method Structure:

Custom Method Examples

Simple Value Retrieval:

[McpServerTool, Description("Get production count for today")]
public string runtime_get_production_count()
{
    return @Tag.Production.TodayCount.ToString();
}

With Error Handling:

[McpServerTool, Description("Get data for a specific tag with validation")]
public string runtime_get_tag_data(
    [Description("Full tag path")] string tag_name)
{
    try
    {
        if ([email protected](tag_name))
            return $"Error: Tag '{tag_name}' not found";

        return @Tag[tag_name].ToString();
    }
    catch (Exception ex)
    {
        @Info.Trace($"MCP Error: {ex.Message}");
        return "Error: Unable to retrieve data";
    }
}

Aggregated Data:

[McpServerTool, Description("Get summary of all tank levels")]
public string runtime_get_all_tank_levels()
{
    var result = new StringBuilder();
    for (int i = 1; i <= 4; i++)
    {
        var level = @Tag[$"Tank{i}_Level"].Value;
        result.AppendLine($"Tank {i}: {level}%");
    }
    return result.ToString();
}

Important: After creating or modifying custom methods, fully restart the AI client (close from Task Manager, not just the window).

Deprecated / Removed Tools

Customers upgrading from 10.1.4 should update any AI prompts, solution-authored wrappers, or integration scripts that reference the old tool names. Bit positions in ModelOptions are unchanged — existing solutions decode identically; only the tool surface and category labels changed.

Best Practices

For AI Queries

• Be specific about tag paths when asking for values
• Use "active alarms" for current state, "alarm history" for past events
• Specify time ranges clearly for historical queries
• Ask the AI to browse the namespace if you're unsure of tag names

For Custom Methods

• Use descriptive names and descriptions — the AI relies on these
• Include parameter validation and error handling
• Return clear error messages that help the AI understand what went wrong
• Follow snake_case naming convention for consistency
• Keep methods focused on single tasks

Security Considerations

• Use X_API_KEY authentication for HTTP connections
• Configure appropriate runtime user permissions
• Be cautious with write operations — consider read-only access for AI
• Review custom methods for security implications

Troubleshooting

AI Runtime server not starting

• Verify the cross-platform .NET Desktop Runtime matching your FrameworX version is installed (.NET 8 for 10.1.4 and earlier, .NET 10 for 10.1.5 and later)
• Check firewall settings for the configured port
• Confirm RuntimeMCP.exe path is correct in AI client config

AI cannot access methods

• Ensure solution is running (the TServer.exe application is running)
• Verify AI client configuration matches server settings
• Restart AI client completely (close via Task Manager)
• Check that MCP decorators are properly applied to custom methods

Data not updating

• Confirm tags are properly configured in the solution
• Verify real-time database connectivity
• Check custom method error handling for exceptions

Custom methods not appearing

• Verify class type is set to "MCP Tool"
• Check for syntax errors in method code
• Restart AI client completely after changes

HTTP connection failing

• Verify ListenPort is not blocked by firewall
• Check X_API_KEY matches between server and client
• For HTTPS, verify certificate is properly configured
• Test with http://localhost:10120 first before remote access

Related Documentation

Quick Start Tutorial

• AI Runtime Tutorial — Creating and deploying MCP Tools

Example Implementation

• SolarPanels MCP Demo — Full solution demonstrating MCP Tools with solar panel monitoring

Technology Information

• AI-Ready by Design — Platform architecture for AI integration

Reference Information

• Scripts Module Reference — Complete scripting documentation

AI Designer

For AI-assisted solution configuration (creating tags, displays, alarms):

• AI Designer Connector — Enable AI to configure solutions
• AI Designer In Action — See AI Designer capabilities in action

Change Log

Technical Specifications

Prerequisites

• FrameworX 10.1 or later
• .NET 8.0 runtime
• Claude Desktop or compatible MCP client
• Network connectivity

Configuration Workflow

According to the claude documentation, there are three ways of connection to the MCP Server:

1. stdio
2. HTTP
3. SSE 

stdio

The following configuration uses stdio, which requires the MCP server to run on the same machine as the LLM. Therefore, if your solution is hosted on a remote machine, you must install the product in both environments: the local machine (where the LLM runs) and the remote machine (where the runtime is hosted).

Configure your AI client (e.g., Claude Desktop) to connect to the MCP server:

{
  "mcpServers": {
    "YourSolution": {
      "command": "C:\\FrameworX\\fx-10\\net8.0\\TMCPServerStdio\\TMCPServerStdio.exe",
      "args": ["/host:127.0.0.1", "/port:3101"],
      "transport": "stdio"
    }
  }
}

HTTP

1. Program: TMCPServerHttp.

2. Install Path (installed using standard Install program):

   1. fx-10\net8.0\TMCPServerHttp\ (NET 8.0 Runtime required to execute TMCPServerHttp.dll)

3. Arguments in MCP Client (Ex: .mcp.json):

   1. Url:<url>: Endpoint containg Host:Port. Ex: http://localhost:3000, https://192.168.20.2:3000

   2. Headers: X_API_KEY (optional) used by authentication

4. Arguments in TMCPServerHttp.json (MachineSettings):

   1. X_API_KEY: (optional) used by authentication

   2. /CertFileName:<filename>:Certificate file name. Used by HTTP/SSL. Work with “CertPass“.

   3. /CertPass:<pass>:Certificate password. Used by HTTP/SSL. Work with “CertFileName“.

   4. /CertHash:<hash>:Certificate Thumbprint. Used by HTTP/SSL. Located at: (StoreName.My, StoreLocation.LocalMachine)

   5. /ListenPort:<port>: Port to listen (endpoint). Default is 3000

   6. Runtime section:

      1. /Host<host>: Runtime Host/IP where runtime is running. Default is localhost

      2. /Port:<port>: Runtime Port where runtime is running. Default is 3101

      3. /UserName<name>: User name used by connection to runtime

      4. /Password:<pass>: User password used by connection to runtime

5. To connect to several runtimes and/or listen several ports, call TMCPServerHttp with argument “/instance:<number>“.

   1. Arguments in section “4” must include “instance”.

   2. Example: TMCPServerHttp /instance:2 => X_API_KEY2, ListenPort2, Runtime2, etc…

{
   "servers": {
    "FrameworX Runtime - HeaderLayout": {
      "type": "http",
      "url": "http://localhost:3000",
      "headers": {
        "X-API-KEY": ""
      }
    }
  }
}

{
  "appSettings": {
    "X_API_KEY": "",
    "CertFileName": "",
    "CertPass": "",
    "CertHash": "",
    "ListenPort": "3000",
    "Runtime": {
      "Host": "localhost",
      "Port": "3101",
      "Username": "guest",
      "Password": ""
    }
  }
}

SSE

SSE configuration was not tested.

Available Methods

When MCP server is running, by default you have three methods:

1. Get Value
2. Get Historian
3. Get Alarms

And you could have many more, by just creating a custom method, for that follow the steps below:

1. Navigate to Scripts → Classes
2. Create new class, select MCP Tool type
3. Define methods using MCP decorators, where:

• Description is the question you will ask the LLM.

• MethodName is what the LLM will call. Each capital letter will appear as a space in the LLM interface.

  • Example: GetTankLevel will appear as "Get Tank Level".

• ParametersDescription explains what is expected for each parameter.

• Parameters define the inputs.

• Content defines the behavior or response of the method.

• Result is what the LLM will receive in order to generate the answer, which it will then convert into a more human-readable response.

[McpServerTool, Description("<Description>")]
public string <MethodName>(
[Description("<ParametersDescription>")] <Parameters>)
{
	<Content>
    return <Result>;
}

Example:

[McpServerTool, Description("Get current tank level")]
public string GetTankLevel(
[Description("Tank identifier")] string tankId = "4")
{
    return @Tag.Tank_{tankId}_Level"].ToString();
}

How to verify if the setting was done correctly

1. Click in the LLM connector, you should see the <SolutionName> name.
2. Go in Settings > Developer, and check if your solution is in a good state (running). (depends on the LLM).

Query Through AI

Once configured, the AI can access your solution data:

General questions

• What is the Server.SystemMonitor.Uptime of BottlingLine MCP Demo?
• Get value of Tag.Machine1.Temperature1

Alarm

• Is there any active alarm, or has there been one recently? Any acknowledged?
• Retrieve the alarms again, and check how many acknowledged alarms do we have? and how many are not?

Historian

• Retrieve the historical Brewery/BrewHouse/Temperature values from today.
• Show a trend visualization (only the trend) with the historical values of Brewery/BrewHouse/Temperature from today in JSX format
• Get all the historical value from today and return the highest and the time that hapenned

Custom Methods (methods you created)

• Get the last anomalies from the Bottling Line

Getting Started

Quick Start Tutorial

Build your first MCP Tool and connect it to Claude AI:

How to Build an MCP Tool - Step-by-step guide for creating and deploying MCP Tools

Example Implementation

Explore a complete working example with MQTT integration:

SolarPanels MCP Demo - Full solution demonstrating MCP Tools with solar panel monitoring

Best Practices

Security Considerations

• Authentication - Implement proper authentication for MCP endpoints
• Authorization - Define clear permission levels for AI operations
• Validation - Always validate AI-generated parameters before execution
• Audit Trail - Log all AI-initiated actions for compliance

Performance Optimization

• Cache frequently accessed data
• Implement rate limiting for AI queries
• Use asynchronous methods for long-running operations
• Monitor resource usage of MCP server process

Error Handling

[McpServerTool, Description("Safe data retrieval")]
public string GetData(string tagName)
{
    try
    {
        if (!@Tag.Exists(tagName))
            return $"Error: Tag {tagName} not found";
        
        return @Tag[tagName].ToString();
    }
    catch (Exception ex)
    {
        @Info.Trace($"MCP Error: {ex.Message}");
        return "Error: Unable to retrieve data";
    }
}

Troubleshooting

MCP Server not starting

• Verify .NET 8.0 runtime installation
• Check firewall settings for configured port
• Confirm TMCPServerStdio.exe path is correct

AI cannot access methods

• Ensure MCP decorators are properly applied
• Verify solution is running (Runtime → Startup)
• Check AI client configuration matches server settings
• Verify is .NET 8.0 is installed in your computer
• Restart your LLM completely after run the solution.

Data not updating

• Confirm tags are properly configured
• Verify real-time database connectivity
• Check MCP method error handling

Related Documentation

In this section...