# Permissions and troubleshooting

> Diagnose missing MCP tools, attachment and revision failures, quote refusals, uncertain actions, omitted results, and unavailable Run Inspector presentation.

Source: https://kaitoi.io/docs/core/mcp-troubleshooting/
Section: Kaitoi Core / MCP
Written for: People diagnosing Kaitoi MCP access, state and result problems.
Last reviewed: 2026-10-24

---

Diagnose the connection, context, operation and result independently. Start
with reads and retained IDs; a new paid run or broader permission is not a
generic connection test.

## Locate the failed layer before repeating work


Check connection and authentication first, then the intended Studio session and its Agent access. Inspect project and graph revisions before repairing a conflict. For an execution problem, retain and inspect the existing receipt and error. A tool missing from the client is not fixed by rerunning a node. Share cleaned identifiers and exact errors without keys or private output.

Each selected fault reveals its matching evidence: missing tools, changed tab binding, revision 7 versus 8, an original action or execution receipt, or an omitted retained-result branch. Later boundaries are not automatically diagnosed by the selected read.

*Figure: Connection, attachment, state and execution require different recovery.*

## Tools are missing

Check the exact environment URL, supported MCP authentication, current client
connection, scopes, account capabilities and tool profile. A server saved in
client settings does not prove its tools are loaded in this conversation.
Read `get_mcp_guide` when available. Do not invent an unavailable tool name or
substitute a REST key for the MCP credential.

## The live tab cannot be used

Enable Agent access on the intended tab and inspect listed sessions.
Attachments are context-bound and short-lived; reread after reconnect or a
project/workspace change. An unavailable/expired attachment is not permission
to continue on a headless graph. Attached project loading can be unavailable
even when read, edit, or save actions are supported.

## A mutation or run is refused

| Symptom                     | Read or check before another action                |
| --------------------------- | -------------------------------------------------- |
| Stale editor revision       | Current attachment and graph state                 |
| Stale media revision        | Current media and editor revisions together        |
| Source hash mismatch        | Actual editor buffer and source hash               |
| Saved version conflict      | Current saved bundle, then reconcile               |
| Missing required input      | Actual schema and intended input value             |
| Cost preflight unavailable  | The unavailable prerequisite; no dispatch occurred |
| Quote expired or mismatched | Fresh bound preview and approval for changed terms |

Do not replace a guard value without comparing the content it protects. A
confirmation flag does not bypass quote context or establish human approval.

## An outcome is uncertain

**Access:** verify connection, scope, capability, profile and intended tab;
do not use paid execution as a probe. **Uncertain write:** read the original
actionId or executionId and preserve its logical key before another attempt.
**Incomplete display:** use the matching value reader and version; absence
from a bounded response does not prove an empty output.

## A result is truncated or cannot be displayed

Use the indicated exact-version graph, execution, action or capture value
reader for omissions. Finish all needed pages and paths. Check whether a
media URL expired independently of retained result availability. A host
without Run Inspector can still use structured results.

Keep `actionId`, `executionId`, result versions, attachment handles and
idempotency keys distinct in a sanitized report. Avoid exposing credentials,
private prompts or source media. See [Live sessions](/docs/core/mcp-studio/),
[Execution approvals](/docs/core/mcp-execution/), and
[Results](/docs/core/mcp-results/) for the appropriate recovery tool.