Diagnose Off, Read-only, locked, ambiguous, no_match, pending, and unknown states, then stop or hand off at unsupported product boundaries.
Loading...
Diagnose the Runtime you are actually connected to before interpreting a failed task. Ask the Agent to read Runtime info and report:
Check the app version in Mqttable's Version and Runtime status panel because MCP does not report the desktop version. A copied URL, an old screenshot, or a previous session does not prove the current Runtime identity.
If the Runtime identity, target Broker, or entitlement is missing, stop before capability search or mutation. Do not guess from source code or another machine.
Mqttable exposes three user-controlled states in Settings > MCP.
| UI state | Runtime behavior | What to do |
|---|---|---|
| Off | The /mcp endpoint rejects the request. A local client can receive HTTP 403 with MCP access is off. | Enable MCP in the current Mqttable app, then reconnect or retry the read once. |
| Read-only | Reads remain available. A mutable plan returns applyable: false, status: disabled, and mutable_access_unavailable. | Keep diagnosing, or ask the user to choose Allow changes. Never work around it through another API. |
| Allow changes | Runtime info reports approved_changes; eligible plans can be created and applied. | Still inspect the exact target, risk, validations, and masked_diff before applying. |
Configured and effective access can differ when the Runtime is degraded. Treat effective access as authoritative and report the degraded reason. Do not claim that a Settings selection proves a mutation was applied.
Search once for an unknown business operation, then follow the typed result.
| State | Meaning | Safe next step |
|---|---|---|
exact | One typed capability matches. | Read that exact schema. |
candidate | One likely typed capability is returned, but its summary or boundary may narrow the request. | Read its schema and confirm it still matches the requested operation. |
ambiguous | More than one typed capability could match. | Choose only when the user's operation identifies one match; otherwise ask. Do not mutate from similarity alone. |
no_match | No typed capability matches. The fallback catalog is discovery context, not an executable plan. | Stop or hand off. Do not retry synonyms until something looks close. |
locked | The capability exists but the current entitlement does not expose its executable schema. | Report required_plan, the summary, and the named fallback. Use the fallback only for its own narrower result, never as equivalent. |
A Free session can prove that a Pro action is locked, but cannot prove the Pro workflow succeeds. For example, a draft-only PCAP Replay candidate does not unlock Replay execution, and Free Trace cannot replace a PCAP analysis.
Mutation success is not the same as receiving an apply response. Read the structured state and follow its recovery contract.
| State or field | Interpretation and response |
|---|---|
planned, applyable: true | Review expiry, target, preconditions, risk, validations, side effects, and masked_diff. Apply the same Plan ID at most once. |
committed | A side effect was reported. Run Verify and reread the affected resource. |
state_matches_but_attribution_unproven | Current state matches the plan, but operation attribution is not proven. Preserve this wording. |
reconcile_pending | Saved state changed, but Runtime synchronization is deferred, often because a Connection is stopped. Reread until the needed terminal condition is observable. |
outcome_unknown or effect_possible | Do not replay the mutation. Call Verify only, then perform a bounded authoritative read. |
failed with no_effect_proven | Correct the validated input only when the recovery contract allows it. |
not_applicable | No mutation was attempted, such as a schema, authorization, or search failure. |
has_more: true or a non-null next cursor | The result is incomplete. Continue within the same bounded query context before making a completeness claim. |
For a scheduled operation, pending, running, disconnecting, idle, completed, and cancelled describe different points in its lifecycle. State the exact value and wait for the tutorial's required terminal condition. Never translate pending into success.
The compact surface stays small while typed Actions, Resources, and Workflows live in the registry.
mqttable_runtime_info reads Runtime identity and access boundaries.mqttable_doctor reads bounded diagnostics and can run an explicit active probe.search_mqttable_capabilities discovers one unknown business operation.get_mqttable_schema reads one exact typed contract and example.execute_mqttable_read runs a no-effect Action or registered Workflow.read_mqttable_resource reads one bounded Resource URI.plan_mqttable_action creates an immutable plan for one mutation.apply_mqttable_plan applies only a reviewed Plan ID.verify_mqttable_plan rereads state for that Plan ID.Do not call historical business tool names. Discover the typed Action, read its schema, and use the compact tool named by that schema.
Stop rather than inventing a route around an explicit boundary:
When a capability is Pro-locked, do not copy its hidden schema from source or construct arguments by inference. Obtain the entitlement, read the newly exposed schema, and start a fresh validation.
Stop and give the user an exact handoff when any of these conditions holds:
no_match;masked_diff is incomplete;The handoff should include the exact state, last safe evidence, objects that may remain, and one allowed next action. It should never include a raw secret or encourage replaying an uncertain mutation.