> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data and services

> All business reads and writes live in the Mini App's Node service; the page only calls business APIs that Node provides.

<div className="code-docs">
  <h2 id="methods">
    Choose an access method
  </h2>

  | Method | Good for | Status |
  | - | - | - |
  | Host Connector | Third-party apps the user has authorized in MiniMax Code, such as Notion | <Badge color="green" size="sm">Released</Badge> |
  | CLI child process | Command-line tools already on the machine, started and cleaned up by the plugin | <Badge color="green" size="sm">Released</Badge> |
  | HTTP API / SDK / local files | Services with their own authentication, or local files the user authorized | <Badge color="green" size="sm">Released</Badge> |
  | Unified tool entry | Calling the host's mounted MCP tools and Connectors with one API | <Badge color="blue" size="sm">Coming soon</Badge> |

  Connectors are one option, not a Mini App prerequisite, and a missing Connector doesn't mean the data is unreachable. If the user names a method and it can be verified, use it; otherwise choose by available capabilities, authentication, runtime environment, and the operations you need.

  <h2 id="probe">
    Verify before you build
  </h2>

  Before writing the package, run one read-only query against each data source with the chosen method. Confirm authorization, real parameters, response fields and types, and get a representative record or a real empty result. Write the parser from the shape you observed.

  <Note>
    A query that succeeds in the Agent's terminal doesn't prove it works in the Mini App runtime. CLI, API, and file access still need one real run inside the Node service.
  </Note>

  <h2 id="host-connector">
    Host Connector
  </h2>

  The Node service uses connectors the user has authorized through `context.hostConnector`. Third-party calls use the account the user authorized in MiniMax Code; the Mini App stores no credentials.

  ```json miniapp/miniapp.json theme={null}
  {
    "hostConnectorAccess": { "providers": ["notion"] }
  }
  ```

  * Declare only providers the runtime really needs and that you have verified.
  * `list()` is always available and returns the allowed tools with their input schemas. Use `call()` only after the service is activated, from a request handler, never in `start`.
  * Don't construct or store `toolRef` values, and don't send them to the page. List again after a process restart or a stale reference.
  * When the user signs out, the tool list and authorized references are revoked. After the same account signs in again, call `list()` once more to recover, with no republish. If a different account signs in, old references are revoked for good.

  ```javascript theme={null}
  // Call from a request handler; tool names and arguments come from the inventory and schema you verified
  async function readRecords(context, args) {
    const { tools } = await context.hostConnector.list();
    const tool = tools.find((t) => t.provider === 'notion' && t.name === VERIFIED_TOOL_NAME);
    if (!tool) throw new Error('connector_tool_unavailable');
    const result = await context.hostConnector.call(tool.toolRef, args);
    return parseRecords(decodeHostConnectorValue(result.value));
  }
  ```

  <h3 id="connector-errors">
    Error handling
  </h3>

  Branch on `code`; don't rely on `instanceof` across processes.

  | code | Meaning |
  | - | - |
  | `TOOL_REF_STALE` / `SERVICE_RESTARTED` | The reference expired or the service restarted; call `list()` again |
  | `INVALID_ARGUMENTS` | Arguments don't match the schema; `diagnostic.issues` gives `path`, `constraint`, and `limit`, never the argument values |
  | `CONNECTOR_UNAVAILABLE` | The connector is currently unavailable |
  | `CONNECTOR_TIMEOUT` / `REQUEST_CANCELLED` | Timed out or cancelled |
  | `CONNECTOR_PROVIDER_ERROR` | The third-party service reported an error. If the cause is unknown, don't assume it is an authorization problem |
  | `CONNECTOR_OUTCOME_UNKNOWN` | The request went out, but its outcome is unknown |

  `disposition` tells you whether the request went out: `not_dispatched`, `provider_reported`, or `unknown_after_dispatch`. For `unknown_after_dispatch`, read the business state to reconcile before deciding whether to retry a write.

  <h3 id="decode">
    Decoding results
  </h3>

  `result.value` is the third-party service's raw result; the host doesn't normalize it. The Skill's `host-connector-value.mjs` unwraps the common single-text-block envelope and passes every other shape through unchanged. Zero parsed items count as success only when the service explicitly returned an empty result; if there is source data but nothing parses, treat it as a parse error, not as "no data".

  <h2 id="state">
    State and persistence
  </h2>

  * Keep runtime data in `context.dataDir`, not in the workspace or the payload.
  * Route every write from the page, MCP calls, and Agent operations through one Node business service. Commit state before pushing SSE or WebSocket events so every open page refreshes to the latest data.
</div>