AI Runtime Connector

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 (In this documentation it might mention "AI Client", but all the tests were done using Claude from Anthropic)
• Running FrameworX solution (TServer.exe)
• Network connectivity

Configuration

The MCP Server starts automatically when your solution runs. To connect an AI client you install the FrameworX extension that matches how the client reaches the runtime. No manual editing of the AI client configuration file is required.

The FrameworX installer creates the setup folder on the machine where FrameworX is installed:

C:\Users\<user>\Documents\FrameworX\AISetup

This folder holds one ready-to-install extension bundle per connection method.

Local Access: Same Machine

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

Step 1 — Install the extension

1. Open Claude Desktop
2. Go to File → Settings → Extensions
3. Click Advanced Settings
4. Click Install Extension
5. Select frameworx-runtime-mcp.mcpb from the AISetup folder
6. Click Install, then Install again on the confirmation popup

Step 2 — Adjust the installation folder or port (only if not default)

The extension points at the default FrameworX installation folder, C:\Program Files\Tatsoft\FrameworX, and at the default runtime port 3101. If either differs on your machine, change them here:

1. Go to File → Settings → Extensions
2. Find FrameworX AI Runtime in the list and click Configure
3. Set the FrameworX installation folder to your install path
4. Set the port to the TServer port your solution is running on

Step 3 — Restart Claude Desktop

Fully quit and reopen Claude Desktop so the extension is loaded. See Applying Changes below.

Remote Access: HTTP

Use this method when the AI client runs on a different machine from the FrameworX solution. The steps are the same as the local method, with one addition: an HTTP bridge must be running on the FrameworX machine.

Step 1 — Install the extension

On the AI client machine, follow the same procedure as the local method, selecting frameworx-runtime-mcp-http.mcpb instead.

1. Open Claude Desktop
2. Go to File → Settings → Extensions
3. Click Advanced Settings
4. Click Install Extension
5. Select frameworx-runtime-mcp-http.mcpb from the AISetup folder
6. Click Install, then Install again on the confirmation popup

Step 2 — Start the HTTP bridge on the FrameworX machine

On the machine where FrameworX is installed, run RuntimeMCPHttp.exe from the installation folder:

C:\Program Files\Tatsoft\FrameworX\fx-10\net10.0\RuntimeMCPHttp.exe

Adjust the runtime folder to match your FrameworX version (net8.0 for 10.1.4 and earlier, net10.0 for 10.1.5 and later). If you installed FrameworX somewhere other than the default location, use that path instead.

Leave the console window open. From FrameworX 10.1.6, the bridge connects only to a runtime you name. To name it at startup, set Runtime.Host and Runtime.Port in RuntimeMCPHttp.json (see Advanced: HTTP Bridge Settings below). The bridge then connects as soon as the runtime is running, and the start order of the bridge and the solution does not matter. With no runtime named in the file, ask the AI to connect to a solution and execution profile. The AI calls runtime_connect with both values and binds the session to the named runtime. Until then, the runtime tools answer with a no-target message and instructions to connect.

In 10.1.5, the bridge starts looking for a FrameworX runtime immediately. As soon as a solution is running, it connects automatically and the AI client has a live remote connection to the runtime. Order does not matter: you can start the bridge before or after the solution.

Step 3 — Adjust the installation folder or port (only if not default)

Go to File → Settings → Extensions, find FrameworX AI Runtime (HTTP) and click Configure. This variant takes two values: RuntimeMCPHttp Host, the address of the machine running the bridge (default 127.0.0.1), and RuntimeMCPHttp Port, the bridge port (default 10120). Note that this is the bridge port, not the TServer port: the TServer host, port, and credentials are configured in RuntimeMCPHttp.json on the runtime machine.

From FrameworX 10.1.6, enter the bridge's X_API_KEY in the extension's API Key setting to connect from another computer.

Step 4 — Restart Claude Desktop

Fully quit and reopen Claude Desktop so the extension is loaded.

Advanced: HTTP Bridge Settings

From FrameworX 10.1.6, the defaults accept connections from the local machine only. In 10.1.5, the defaults work for a trusted local network. To change the listen port, set an API key, or enable TLS, edit this file on the FrameworX machine before starting the bridge:

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

Multiple Connections: to serve multiple runtimes from one machine, start the bridge with the /instance:<number> argument and add matching numbered settings (for example X_API_KEY2, ListenPort2, Runtime2).

Applying Changes

Claude Desktop loads extensions once, when the process starts. After installing an extension, reinstalling an updated one, or changing values in the Configure panel, you must fully restart the client. Opening a new chat is not enough. The restart of the AI Client is necessary after running the solution as well.

• Windows: Close the process in the Task Manager. Only closing the AI Client window is not enough.

Verifying Connection

1. In the chat, click in the '+' button > Connectors > See if "FrameworX AI Runtime" is listed there. 
2. Ask the AI a simple question like "What is the server uptime?"

Available Tools

AI Runtime provides built-in platform tools plus solution-authored custom tools, organized by category. The tool count your AI client reports is the sum of both. 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 hierarchy that includes the Unified Namespace (Tag.*) plus the built-in namespaces (Server, Client, Alarm, Device, Historian, Dataset, Script, Display, Layout, Security, Report, Info, Enumeration, TagProvider).

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.

Wait Tool (1 tool)

From FrameworX 10.1.6. Read-only. Available in the stdio and HTTP connectors. The tag condition needs Enable UNS Tools, the alarm condition needs Enable Alarm Tools, and the module condition needs the master toggle only.

Client Session Tools (Development only)

Tools for inspecting and driving connected client sessions during local development and automated testing. They are not general operations tools and are not exposed through the MCP for Runtime gate panel. From FrameworX 10.1.6a, the AI Runtime server lists them only when it starts with /AllowTestTools:true, which is off by default. On the HTTP server (RuntimeMCPHttp), the option takes effect only when the server accepts local connections only. Each one answers only when all of the following hold: the runtime's QaTestMode gate is active, the caller reaches the runtime over true loopback (127.0.0.1 / ::1), the target client’s connection and the address it reports are both true loopback, and this MCP host is on a transport a remote caller cannot reach (STDIO always; HTTP only when launched with ListenLoopbackOnly=true). When a gate refuses, the tool returns an errorCode and a message instead of 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
• From FrameworX 10.1.6a, the AI Runtime server offers runtime_force_switchover, which commands a redundancy switchover, only when it starts with /AllowControlActions:true, which is off by default. On the HTTP server, the option takes effect only when the server accepts local connections only. The tool is marked as destructive, so AI clients that confirm destructive actions ask before it runs.

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 the FrameworX installation folder is correct in the extension's Configure panel

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

Connector process stopped or kept running unexpectedly

• From FrameworX 10.1.6, each stdio AI Runtime connector process writes a small lifetime log, McpLifecycle_<Connector>_<pid>.log, in the product TraceLogs folder.
• The log records which launching process and grandparent the connector watches, a fallback to watching the launching process only, a watch it failed to start, and why it shut down after a watched process ended. A clean disconnect by the AI client records no exit reason.
• Each file stops growing at 64 KB, and files older than 30 days are removed.
• The HTTP bridge (RuntimeMCPHttp) does not watch a launching process.

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

• Confirm RuntimeMCPHttp.exe is running on the FrameworX machine
• 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
• From FrameworX 10.1.6, set X_API_KEY on the bridge for access from another machine. With no key, the bridge accepts local connections only.

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

In this section...