MCP operation reference
Connection setup, operation groups, mutation rules, prompts, and safe agent workflows.
MCP operation reference
The MCP server exposes the currently open Busloom desktop session over loopback-only Streamable HTTP. Every request requires the generated bearer token. Tools adapt visible Busloom operations; they do not maintain a shadow project, second connection, or independent register cache.
Client connection contract
| Property | Requirement | Operational note |
|---|---|---|
| Transport | Streamable HTTP | Use the URL shown in Application Preferences → MCP |
| Network | 127.0.0.1 only | Remote machines cannot connect directly; do not proxy the listener casually |
| Authentication | Authorization: Bearer <token> | Regenerating the token restarts the enabled server and invalidates existing clients |
| Desktop lifetime | Busloom remains open | The MCP server controls the open session and stops with it |
| Entitlement | Professional | The native server verifies the feature rather than relying only on the settings UI |
Operation groups
| Group | Representative capabilities | State boundary |
|---|---|---|
| Project | Create, open, inspect, validate, replace, save, Save As, list recent/discoverable projects | Mutations enter ordinary undo/history; saving remains explicit |
| Profiles and connection | Create/update/duplicate profiles, enumerate serial ports, connect, disconnect, read status | One shared selected profile and serialized native connection |
| Discovery | RTU Unit-ID discovery, TCP/TLS subnet and port discovery, progress polling | Inputs and result sizes are bounded; long work can be started and polled |
| Views and tags | Create/edit/delete views and groups, import/export maps, start/stop/run once, read decoded values | Uses the same project validation and native value store |
| Public device catalog | Refresh/search entries, fetch definition, preview and apply atomic merge | No definition can carry endpoints, credentials, automation, or executable code |
| Writes | Write one decoded tag or run write-capable automation | Visible prompt by default; read-only profile always blocks |
| Diagnostics | Auto Scan, Device Info, Connection Health, Protocol Diagnostics, Raw Traffic | Same transaction journal and source attribution as the UI |
| Trends and alarms | Manage series, observe samples, create rules, read state/history, acknowledge, export, render report | Definitions may be project-owned; samples and acknowledgement are session-owned |
| Automation | Manage resources, validate, dry-run, execute, stop, inspect and export reports, compare results | Same runner, limits, cancellation, and connection priority as the desktop |
| Replay and Git | Open session/report artifacts, inspect replay, read file status/history, create project-only version | Never opens a replay transport; Git remains local and project-file scoped |
Mutation and prompt rules
- Project edit
- Validated and applied to the open document. It may make the project dirty but does not silently write the file.
- Device change
- Tag writes and real write-capable automation require visible approval unless Allow changes without prompts is explicitly enabled.
- Read-only profile
- The final native guard. It blocks changes even when prompts are disabled or a client asks for a direct write.
- Fingerprint guard
- A complete project replacement can require the expected project fingerprint so stale clients cannot overwrite a newer document accidentally.
- Absolute artifact path
- MCP file operations require explicit absolute paths so a background tool never blocks on a native file picker.
Build a bounded agent workflow
Inspect before mutation
Read current project summary, active profile, connection state, and the target resource before changing it.
Bound discovery
Name the interface, subnet or Unit-ID range, timeout, and intended scan mode. Start long work asynchronously and poll its status.
Preview imports
Fetch a device definition or table mapping, inspect additions/updates/issues, then make a separate apply request.
Prove acquisition
Start the required sources, observe a bounded number of samples, and retain raw or health evidence before interpreting changes.
Dry-run changes
Validate or dry-run write-capable automation, then request explicit approval for the real operation.
Save deliberately
Review the ordinary dirty project in Busloom and call save only when the requested mutation should persist.