Runtime MCP Reference

Live-runtime MCP surface for FrameworX. Read tags, alarms, historian, and UNS state from a running TServer.

AI Integration → Runtime MCP Reference

Vocabulary vs. DesignerMCP and ConsoleMCP

RuntimeMCP tools carry a runtime_ prefix so the mode is always obvious in a transcript. The design-time tools in DesignerMCP and ConsoleMCP work on configuration (the solution); the runtime tools work on state (the running process).

The runtime_ prefix is load-bearing — do not unify names with DesignerMCP. A tool name is the agent's strongest cue about which world it is talking to.

Server Variants

RuntimeMCP ships as three executables, each tailored to a deployment shape.

All three share the same tool surface. The HTTP variants add bearer-token authentication through the configured API key in RuntimeMCPHttp.json. Use a reverse proxy if you expose the HTTP surface beyond a trusted subnet.

Connection Identity — (solution, profile)

A FrameworX runtime is identified by which solution it is running and which Execution Profile it is running under. The same .dbsln can run concurrently under multiple profiles (Production, Development, Validation, Custom), each bound to its own TCP port via the solution's RuntimeExecutionProfiles configuration. Port is a consequence of the active profile, not an identity; editing profile port offsets in the solution changes the port without changing what solution or profile is running.

RuntimeMCP therefore accepts solution and profile as the connection coordinates. Port is looked up at bind time from InfoServer's registry of running TServers and returned to the client in the bind response for observability.

Profile values:

Aliases are case-insensitive. Responses always echo both the canonical integer and the full profile name.

Startup Modes (HTTP only)

RuntimeMCPHttp supports two startup modes. The stdio RuntimeMCP binary is always process-per-session and retargeting it means restarting the subprocess — modes do not apply there.

Retargetable (default)

Accepts runtime_connect(solution, profile) at runtime to switch the bound TServer without restarting the process. Designed for automated tests that drive many targets from a single long-running MCP instance. The initial target can be supplied via /solution + /profile startup args or deferred until the first runtime_connect(solution, profile) call — tool calls before an initial target return ERR_NO_TARGET.

One Claude Code session per retargetable instance. Retarget state is held in the server process and shared across all connected clients — if two sessions hit the same retargetable instance, the second session's runtime_connect(solution, profile) silently retargets the first session's tools. For multi-session setups, run multiple RuntimeMCPHttp instances on distinct ports in pinned mode.

Pinned

Bound at startup via required /solution + /profile args, immutable for the process lifetime. The with-args branch of runtime_connect is rejected with ERR_PINNED in this mode — agents cannot retarget. The no-args branch (session-info query) remains available. Designed for A/B-style test setups: launch N RuntimeMCPHttp instances on N distinct listen ports, each pinned to its own (solution, profile), and register each as a separate MCP client entry.

Startup argv

RuntimeMCPHttp.exe [/mode:retargetable|pinned]
                   [/solution:"<name>"] [/profile:0-3]
                   [/listen:<port>]         # default 10120
    

/mode defaults to retargetable if omitted. In pinned mode both /solution and /profile are required; missing either is a startup error.

Tool Catalog

Note. RuntimeMCP does NOT expose any write to solution configuration — no write_objects, no delete_objects, no rename_objects. Configuration writes belong to DesignerMCP or ConsoleMCP. RuntimeMCP writes are limited to live Object Model row values via set_object_value, gated by the AI Runtime-Write Gate on the active Execution Profile.

10.1.5 additions. runtime_get_aggregated_history (TDEV-1340) sits alongside runtime_get_tag_history and returns time-bucketed aggregates (min, max, avg, count) computed server-side over a query range — the same shape exposed by the Runtime API /aggregates endpoint and the TK.GetTagHistorianAggregated script API. set_object_value writes a single row in the live Object Model (tag value, attribute, or other runtime-writable object) and is the runtime counterpart to DesignerMCP write_objects (which targets configuration tables, not live state); the write is rejected unless the AI Runtime-Write Gate is enabled on the active profile.

Diagnostic Tools

The runtime_debug_* family exposes internal runtime state for troubleshooting workflows. These tools are read-only diagnostics — they do not mutate runtime state, do not require the AI Runtime-Write Gate, and do not open DataAccess connections beyond what the bound TServer already serves. Use them when a tag, alarm, display, or module is behaving unexpectedly and the configuration looks correct.

All diagnostic tools require the MCP to be bound to a target (same as any other authenticated runtime_* tool) and inherit the bound TServer's bearer-token authentication. They return ERR_NO_TARGET on a retargetable instance that has not yet been bound.

Privilege gating. None of the runtime_debug_* tools require the AI Runtime-Write Gate — they are read-only. They do inherit the bound TServer's authentication: an HTTP variant rejects unauthenticated calls with 401, same as any other authenticated runtime_* tool. The diagnostic surface intentionally exposes internal runtime state, so do not expose the HTTP endpoint beyond a trusted subnet without a reverse proxy.

Ring-buffer scope. The two runtime_debug_recent_* tools read from in-memory ring buffers sized at runtime start and bounded by available memory; older entries are evicted silently. For audited or long-window queries, use runtime_query_alarm_history (alarms) or the Historian / Events module surfaces — the debug tools are for live triage, not the system of record.

runtime_describe_binding

Pre-auth introspection tool. Returns the runtime's /health payload without performing authentication, so an automated verifier can confirm which sandbox a TServer is actually bound to before issuing authenticated runtime_get_value / runtime_browse_object_model calls.

Why pre-auth matters: authenticating against the wrong sandbox produces confusing downstream failures (tag-not-found, namespace-empty, asset-tree mismatch) that look like runtime bugs but are bench-misalignment. Catching the mismatch pre-auth is one MCP call vs. minutes of false-positive triage.

# No args: resolve the target via this MCP's bound (host, port).
runtime_describe_binding()

# Or probe an arbitrary runtime by URL (cross-bench check; this MCP's
# binding is NOT changed).
runtime_describe_binding(tserver_url="host:3201")
runtime_describe_binding(tserver_url="http://host:3201")
runtime_describe_binding(tserver_url="http://host:3201/health")
    

Response shape:

{
  "success":         true,
  "url":             "http://localhost:3201/health",
  "resolved_from":   "current_binding",       // or "argument" | "tserver_cmdline_scan"
  "http_status":     200,
  "status":          "healthy",               // /health "status" field
  "version":         "10.1.5.2034",
  "solution":        "ai-test-mcp-context-menu",
  "started_at":      "2026-05-15T18:02:11Z",
  "uptime_seconds":  4231
}
    

Resolution order when tserver_url is omitted: (1) this MCP's bound CurrentHost / CurrentPort, (2) the MCP's startup args (/Host+/Port or legacy /ip1+/port1), (3) command-line scan of running TServer processes on the host. resolved_from tags which path produced the answer so the caller can see whether the response reflects the MCP's binding or a fallback.

The tool is pure — no DataAccess connection is opened, no search cache is touched, no log is written, the MCP's binding is not changed. The cross-bench form (with tserver_url) leaves the MCP pointed at its existing target.

503 unhealthy. A runtime that is up but mid-startup or shutting down returns http_status: 503 with status: "unhealthy" and a reason field; success is then false but the tool returns normally so the caller can branch on the precise status.

runtime_connect

Single entry point for session and target control. Two branches based on argument presence; both are exposed under the same tool name to keep agent transcripts uncluttered.

No-args branch — session info

Returns the current binding (solution, profile, host, port), the server variant (stdio / HTTP retargetable / HTTP pinned), and version metadata. Always available, regardless of mode. Useful as a first call to confirm what the MCP is talking to.

runtime_connect()
    

With-args branch — bind or retarget

Binds (or rebinds) a retargetable RuntimeMCPHttp instance to a running TServer identified by (solution, profile). Disconnects from the current target, resolves the new target through InfoServer, reconnects, and invalidates the in-process search cache. Atomic from the caller's perspective — on failure the previous target is left intact.

In pinned mode the with-args branch is rejected with ERR_PINNED; run a separate RuntimeMCPHttp instance for each pinned target.

runtime_connect(
  solution="SolarPanels MCP Demo",
  profile=1            # or "dev"
)
    

With-args response includes the new bound target and, if the server was previously bound, the target it was on before:

{
  "solution": "SolarPanels MCP Demo",
  "profile": 1,
  "profileName": "Development",
  "host": "localhost",
  "port": 3201,
  "connected": true,
  "previousTarget": {
    "solution": "Industrial Ontology Demo",
    "profile": 0,
    "profileName": "Production",
    "host": "localhost",
    "port": 3101
  }
}
    

In 10.1.5, all resolved targets use host = "localhost"; remote TServer binding is not supported. The field is returned for forward compatibility.

Replaces. The earlier standalone runtime_set_target tool is now the with-args branch of runtime_connect; the earlier runtime_get_info tool is now the no-args branch. Existing automation that called either should switch to runtime_connect with the same payload (with-args) or no arguments (no-args). See the deprecation table on AI Runtime Connector.

runtime_describe_object

Returns a single live object as the runtime sees it — inheritance chain, derived types, cross-references, and effective values. Two argument shapes select the object: by name (UNS-pathed or short name resolved against the runtime's namespace) or by iri (the runtime's canonical Internationalized Resource Identifier for an object). Exactly one of the two must be supplied.

# By name (UNS-pathed or short)
runtime_describe_object(name="Tag.Plant.Line1.Temperature")

# By canonical IRI
runtime_describe_object(iri="urn:tatsoft:fx:tag:Plant/Line1/Temperature")
    

The response shape is identical across both branches — a single resolved object with its derived types in derivedTypes, its inheritance chain in inheritsFrom, and the values the runtime is currently serving. The branch is a convenience over how the caller knows the object, not a difference in what is returned.

Replaces. The earlier standalone runtime_find_by_iri tool is now the iri=… branch of runtime_describe_object; the earlier runtime_get_object_context tool merged into this tool as well; the earlier runtime_list_derived_types tool was removed entirely — its data is now in the derivedTypes field of this response. See the deprecation table on AI Runtime Connector.

MCP Client Registration

For MCP client configuration (Claude Desktop, Claude Code, VS Code Copilot), register each RuntimeMCPHttp instance as its own HTTP MCP entry. Name the entries semantically — runtime_{solution}_{profile} for pinned instances; runtime or runtime_retargetable for a retargetable instance. Never encode the port in the entry name: ports can change when profile offsets are edited in the solution, and a port-named entry becomes a lie the moment that happens.

Example: side-by-side Dev vs. Production (pinned)

# Launch two RuntimeMCPHttp instances pinned to different profiles
RuntimeMCPHttp.exe /mode:pinned /solution:"SolarPanels" /profile:0 /listen:10120
RuntimeMCPHttp.exe /mode:pinned /solution:"SolarPanels" /profile:1 /listen:10121

# Register in the MCP client as two separate entries:
#   runtime_solarpanels_prod  -> http://localhost:10120
#   runtime_solarpanels_dev   -> http://localhost:10121
    

Tools from each entry carry that entry's name as a prefix in the agent's transcript, so runtime_solarpanels_dev.runtime_search_uns is unambiguously the Development runtime, and side-by-side comparisons are legible.

Example: single retargetable instance for automated tests

# Launch one RuntimeMCPHttp in retargetable mode, no initial target
RuntimeMCPHttp.exe /mode:retargetable /listen:10120

# Register as a single entry: runtime_retargetable -> http://localhost:10120
# Scripted tests call runtime_connect(solution, profile) before each scenario.
    

Ad-hoc HTTP Client Handshake

RuntimeMCPHttp uses stateful Streamable HTTP. Any ad-hoc client — bare-shell curl, Postman, or a custom HTTP wrapper — must perform a three-step handshake before issuing tool calls:

1. POST initialize and capture the Mcp-Session-Id response header.
2. POST notifications/initialized with that Mcp-Session-Id header.
3. POST tools/list or tools/call with the same Mcp-Session-Id header.

Skipping the initialize step returns:

-32000 Bad Request: A new session can only be created by an initialize request
    

Claude Code, Claude Desktop, and any other MCP-aware client perform this handshake transparently — the rule applies only when a script or operator drives the HTTP endpoint directly. The same Mcp-Session-Id must be reused for the lifetime of the session; new POSTs without it are treated as fresh sessions and rejected on subsequent tool calls.

Error Codes

Version History

In this section...