Controls and Resources

Read resources to establish context, then call an exact control against an explicit mounted target.

The MCP server exposes six stable tools. Product operations are discovered as controls and invoked through tradescript_call, keeping tool discovery small without hiding what the mounted product can do.

The model in one minute

Four concepts explain every table on this page:

• Resources are passive reads. tradescript://sessions, per-session context, and the installed-version catalog are read-only URIs; reading one never changes state and never requires a grant beyond pairing.
• Tools are the six commands. Two inspect (tradescript_get_context, tradescript_list_controls), two act (tradescript_call, tradescript_batch), two observe (tradescript_subscribe, tradescript_snapshot). Everything mutable goes through tradescript_call with a catalog control ID.
• Approvals are host-owned policy, not prompts. What an agent may call is the session-effective intersection of the adapter maximum, mounted controller support, surface policy, attachment policy, and broker execution environment. There is no per-call server approval prompt; denied capability appears as unavailableControls facts.
• Sessions are owned by the browser host. One attached adapter is one paired session; the agent holds only an opaque sessionId and must name an explicit target (session, chart, or widget) on every request.

Decide call versus read with this table:

You want to	Do this	Kind
Discover which sessions are paired	Read tradescript://sessions	Resource read
Know what is mounted and its current state	Call tradescript_get_context for one target	Read-class tool
Know what you are allowed to invoke	Call tradescript_list_controls for one target	Read-class tool
Browse installed-version vocabulary (not authorization)	Read tradescript://catalog/controls	Resource read
Change state or execute an operation	Call tradescript_call with one control ID	Write- or trade-class tool
Run several ordered calls	Call tradescript_batch (non-atomic)	Write- or trade-class tool
Watch events over time	Call tradescript_subscribe (start/poll/stop/list)	Read-class tool
Prove rendered output	Call tradescript_snapshot	Read-class tool

Stable v2 tools by developer job

Inspect before acting

Tool	Purpose
tradescript_get_context	Read authorized state, capabilities, revisions, targets, and subscription channels for one explicit target.
tradescript_list_controls	Discover controls effective for one required exact target plus the SDK-owned unavailable and unclassified capability ledger.

Act on a target

Tool	Purpose
tradescript_call	Invoke one returned control against an explicit target with bounded positional arguments and optional expected revisions.
tradescript_batch	Run up to 25 ordered calls. The batch is non-atomic and returns one result per call.

Observe evidence

Tool	Purpose
tradescript_subscribe	Start, poll, list, or stop bounded event subscriptions using exact SDK channel bindings.
tradescript_snapshot	Capture an authorized chart or widget target, including a registered whole-terminal widget, as an MCP image result. Session targets carry semantic state but no rendered root.

The server also publishes the tradescript_operator prompt. It teaches discovery-first routing, revision-conflict recovery, and rendered verification. It grants no authority.

Sessions and targets

Every context read, control call, subscription start, and snapshot identifies one paired session and an explicit target:

{ "scope": "session" }
{ "scope": "chart", "chartId": "chart-id-from-context" }
{ "scope": "widget", "widgetId": "widget-id-from-context" }

Begin with tradescript_get_context on the session target. Its availableTargets list is the routing authority for mounted surfaces. Never derive a target from a visible title or silently substitute the active chart.

Effective control discovery

A control ID joins the controller and public method, such as chart.setVisibleRange, depthLadder.placeAtLevel, or risk.triggerEmergency. Its descriptor includes:

• exact control ID, controller, method, and public SDK signature
• supported session/chart/widget target scopes
• read, write, or trade access class
• exact policy family
• mutation and read/write/financial risk classification
• SDK-owned revision domains
• the options-object index used for guarded operation identity when applicable

tradescript_list_controls requires both sessionId and one exact target; v2 never returns an unattributed union across surfaces. Optional filters include controller, access class, family, permission label, mutation, cursor, and limit.

The response is already session-effective: the adapter maximum, mounted controller support, surface policy, attachment policy, and execution environment have been intersected. controls contains the effective page. unavailableControls carries bounded SDK-owned { control, reason, detail? } facts; unclassifiedControls carries unsupported controls whose source omitted an exact reason. Each ledger includes its own total and truncation flag. Set unavailableLimit from 1 through 1000 to bound the rows returned independently for each ledger; when omitted, the SDK default is 256. MCP transports these facts without inventing or rewriting a reason.

The MCP Control Reference documents the complete control vocabulary. A paired session must still discover its effective controls.

One revision-safe call

Read the owning controller's revisions immediately before a mutation, then carry only the domains declared by that control:

{
  "sessionId": "session-from-resource",
  "target": { "scope": "chart", "chartId": "chart-from-context" },
  "controlId": "chart.setVisibleRange",
  "args": [
    { "startTime": 1735689600, "endTime": 1735776000 }
  ],
  "expectedRevisions": {
    "viewport": 12
  },
  "requestId": "client-request-42",
  "context": {
    "operationId": "visible-range-operation-42",
    "origin": "mcp"
  }
}

The result carries the caller-visible SDK operation ID, MCP origin, before and after revisions, mutation flag, duration, target, and structured control result. Each attachment supplies an opaque operation namespace to the SDK, so two clients may use the same caller operation ID without sharing retry evidence. Every control classified as financial requires a non-empty caller-owned operationId; omitting it fails before broker execution. Non-financial calls may omit it and receive an attachment-unique generated ID. Reuse a caller-owned ID only for a byte-equivalent retry inside the same attachment.

The complete call envelope is bounded before transport. When a successful mutation's structured result cannot fit alongside its identity and reconciliation receipt, result is null and resultOmitted reports the response limit; operation ID, revisions, and mutation evidence remain available.

Revision domains are catalog facts and may grow with new controllers. Read them from the selected descriptor and the owning entry in controllerRevisions; do not rely on a hard-coded global list. On conflict, re-read context and reconsider the intent before sending a new operation.

Batches

tradescript_batch accepts at most 25 ordered calls. It returns atomic: false and exactly one attributed fulfilled, rejected, or skipped outcome per input. The default stops after the first error and marks trailing inputs skipped; stopOnError: false is appropriate only when later calls are independently safe. The backend reserves response space before executing each next call. If the aggregate limit is reached, it keeps a compact receipt for the last executed mutation and marks all remaining inputs skipped with response-size-limit. A successful earlier mutation is not rolled back when a later call fails.

Event subscriptions

Context returns availableSubscriptions for the requested target and effective read policy. Start a subscription with exact returned channel identities:

Every returned descriptor includes an SDK-owned optionsContract and eventContract. Each contract has a public signature, bounded portable schema, and checked example; optionsContract.required says whether options may be omitted. The SDK rejects invalid options before invoking the mounted source and validates the projected event before MCP adds attribution or buffers it. Custom channels use this same discovery and enforcement contract.

{
  "action": "start",
  "sessionId": "session-from-resource",
  "target": { "scope": "session" },
  "bindings": [
    {
      "channelId": "data.quotes",
      "bindingId": "primary-l1",
      "options": {
        "symbols": ["BINANCE:BTCUSDT"]
      }
    },
    {
      "channelId": "trading.events",
      "bindingId": "paper-orders"
    }
  ]
}

Each polled event retains sequence, receipt time, target, channel ID, binding ID, and projected payload. Multiple bindings may use one channel. A failed multi-binding start rolls back earlier bindings, and stop/detach tears each binding down once. SDK target unregistration synchronously invalidates its source listeners and leaves a stopped subscription tombstone with exact time and target-unregistered reason in list/poll results.

The published tradescript_subscribe input schema explicitly exposes the start, poll, stop, and list actions plus their target, binding, cursor, and subscription fields. It does not collapse to an opaque empty object during MCP tools/list discovery.

Buffers and polls are bounded. Buffer eviction and invalid/oversized event projection both advance droppedBeforeSequence; a returned sequence gap is never presented as complete history. Recover from current controller context when drop evidence is present. MCP is a semantic control and supervision plane, not a lossless high-rate market-data transport.

Resources

URI	Contents
tradescript://catalog/controls	Complete control and subscription vocabulary for the installed version.
tradescript://sessions	Bounded summaries for currently paired sessions.
tradescript://sessions/{sessionId}/context	Read-only session-target context for one paired session.

Resources are read-only. The catalog resource documents vocabulary, while tradescript_list_controls is authoritative for effective controls. Snapshot capture is a tool because image export is an explicit bounded operation.

Trading and risk controls

Financial controls use the trade access class. Exact broker operation support, broker-declared paper/live mode, host risk authority, policy intersection, revisions, and operation identity all remain enforced upstream in the SDK.

Order, position, and execution chart lines use chart.createTradingLine, chart.getTradingLine, chart.listTradingLines, chart.updateTradingLine, and chart.removeTradingLine. These return serializable identities and state suitable for MCP calls and evidence.

Default transport limits

• 25 calls per batch.
• 16 positional arguments per call.
• 256 KB request JSON.
• 2 MB normal result JSON.
• 12 MB decoded snapshot.
• 32 active subscriptions per session and 32 bindings per subscription.
• 256 buffered events and 100 events per poll.
• JSON depth 24 and strings up to 128 KB.

Prefer target-local filtered discovery and small state windows. Do not request unbounded bars, object trees, tape, depth, account history, or event logs.

Next steps

• MCP Control Reference — every control, its signature, access class, and policy family.
• MCP Security and Access — read, write, and trade authority, and how each layer narrows it.
• Agent Recipes — capability-gated workflows built from these tools.
• MCP Troubleshooting — revision conflicts, missing controls, and partial batches.