Data and services

Choose an access method

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

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.

Verify before you build

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.

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.

Host Connector

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.

miniapp/miniapp.json

{
  "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.

// 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));
}

Error handling

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.

Decoding results

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”.

State and persistence

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.

Get started

Learn

Develop

Reference

Choose an access method

Verify before you build

Host Connector

Error handling

Decoding results

State and persistence

​Choose an access method

​Verify before you build

​Host Connector

​Error handling

​Decoding results

​State and persistence

Choose an access method

Verify before you build

Host Connector

Error handling

Decoding results

State and persistence