Diagnose MCP enablement, runtime health, 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.
Settings > MCP has one enablement switch, separate from runtime health.
| State | Runtime behavior | What to do |
|---|---|---|
| Off | /mcp rejects requests with HTTP 403 and MCP access is off. | Ask the user to enable MCP in the current app. |
| Enabled and healthy | enabled: true, runtime_health: ready; supported reads and changes are available. | Inspect the exact target and input before Execute; check the returned operation evidence. |
| Enabled, change services unavailable | enabled: true, runtime_health: unavailable; writes are rejected while available diagnostic reads remain. | Report runtime_health_reason; never bypass failed gates. |
Old access-level settings require explicit re-enablement. An enabled switch is not proof that a change was applied; use the operation result.
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 permission to execute. | 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.
Execute once with a stable idempotency key. A response timeout does not prove that a message, subscription or fault did not happen.
| Status | Meaning |
|---|---|
completed | The action's completion condition is proven. |
pending | Execution, required input or observation is pending. |
not_executed | No business effect occurred. |
partial | Only part of the requested outcome is confirmed. |
outcome_unknown | Query the original operation; do not repeat the effect. |
effect_state separately reports whether effects are absent, possible or confirmed. Query operation.read with either the operation ID or the original idempotency key. Missing or inaccessible history is not proof of non-execution.
The compact surface stays small while typed Actions, Resources, and Workflows live in the registry.
find_mqttable_capabilities discovers one unknown business capability.describe_mqttable_capability reads one exact typed contract and example.query_mqttable runs a no-effect Action or Workflow, reads a Resource URI, or executes an Action-only bounded batch.execute_mqttable_action executes one authorized action with effects and durable idempotency.diagnose_mqttable reads bounded Mqttable diagnostics and can run an explicit active probe.Deleted tool names are not aliases. Discover the typed Action, read its contract, and use the current tool named by that contract.
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;outcome_unknown and operation.read cannot establish the required state;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.