OPC UA MCP Server

Overview Schema Source Related Servers Discussions Admin

read_opcua_history

Read-onlyIdempotent

Retrieve a node's stored values over a time range, either as raw readings or per-interval aggregates for trends, excursions, counts, or totals.

Instructions

Read what a node's value has been over time. Without aggregate_function this returns the raw stored readings, with ReturnBounds=false: no preceding/following boundary values or BadBoundNotFound placeholders. With it, the server computes one summary value per processing_interval over the range instead — 'Average' for a trend, 'Maximum'/'Minimum' for excursions, 'Count' for how often something was recorded — which is how to ask about a week of data without transferring a week of data. Needs a server that keeps history (AccessHistoryDataCapability) or offers aggregates, and aggregate_function needs the aggregates; a call the connected server cannot serve is refused with capability_not_supported and a suggestion, before anything is sent. get_server_status reports which of the two the server offers, and its aggregate function names. Aggregate reads follow native continuation points within the same call, preserving the original interval anchor; they return the completed range or an explicit error within the 5000-value bound. The structured result's completeness says whether the range held more than came back and how to continue; never infer that from the number of records.

Input Schema

Name	Required	Description
`node_id`	Yes	The OPC UA node ID to read history for. Example: 'ns=2;i=2'.
`end_time`	No	End of the time range, ISO-8601 with a timezone. Defaults to now.
`num_values`	No	Maximum number of raw readings to return, capped at 5000. 0 (the default) means as many as that cap allows, not every reading in the range — a raw read of a year of fast data is a request that never returns. When the cap is reached the result says so, and the way to see the whole range is `aggregate_function` rather than a bigger number. Ignored when `aggregate_function` is given, where the number of results is decided by `processing_interval`.
`start_time`	No	Start of the time range, ISO-8601 with a timezone: '2026-09-09T12:00:00Z' or '2026-09-09T14:00:00+02:00'. A timestamp with no timezone is refused rather than guessed. Required when `aggregate_function` is given; for a raw read, defaults to one hour before `end_time`.
`aggregate_function`	No	Summarise each interval with this OPC UA aggregate instead of returning raw readings, by its OPC UA name: 'Average', 'Minimum', 'Maximum', 'Count', 'Total', 'Interpolative', ... Which ones the connected server offers is its own choice, listed by get_server_status under capabilities.aggregate_functions; a name it does not offer is refused with the list it does.
`processing_interval`	No	Width in milliseconds of each interval the aggregate is computed over. 0 (the default) makes the whole range a single interval, giving one result. Only meaningful with `aggregate_function`.

Output Schema

Name	Required	Description	Default
`result`	Yes
`completeness`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 5, 2026

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: ReturnBounds=false with no boundary values or BadBoundNotFound placeholders, a pre-flight capability_not_supported refusal with a suggestion before anything is sent, continuation-point handling that preserves the interval anchor, and the 5000-value bound. It stops short of describing the shape of the returned records, leaving that to the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the raw-versus-aggregate fork before any caveats, which is the right order. It is a dense single block, though, and a few phrases ("which is how to ask about a week of data without transferring a week of data") spend words on rhetoric rather than new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers what an agent needs to call this correctly on a complex 6-parameter tool: mode selection, capability preconditions, error behavior, size limits, and an explicit instruction to read the structured result's completeness field rather than counting records. Return-value detail is delegated to the output schema, which exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter docs are already thorough, including the num_values cap semantics, the timezone requirement on start_time, and the interaction between aggregate_function and processing_interval. The description mostly restates those rules in prose, adding only the reasoning that aggregate reads preserve the original interval anchor, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Read what a node's value has been over time") and immediately splits the tool into its two distinct modes: raw stored readings versus aggregate summaries. The capability gating and the pointer to get_server_status make it distinguishable from read_opcua_nodes and the other history siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use each mode: omit aggregate_function for raw readings, supply it to ask about a week of data without transferring a week of data, and use it rather than raising num_values when the cap is hit. It also names prerequisites (AccessHistoryDataCapability or aggregate support) and routes the agent to get_server_status to discover which applies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server