Data and services

​

Choose an access method

​

Verify before you build

​

Unified tool entry

{
  "toolAccess": ["call"]
}

// Call from a request handler after activation; verify names, arguments, and results with a real read
async function callVerifiedTool(context, args) {
  const { tools } = await context.tool.list();
  const tool = tools.find(
    (item) => item.kind === 'mcp' && item.server === VERIFIED_SERVER && item.tool === VERIFIED_TOOL_NAME,
  );
  if (!tool || tool.permission === 'deny') throw new Error('tool_unavailable');
  return context.tool.call(tool.name, args);
}

• Take name from list(), matching kind, server / provider, and tool; never construct tool names. list() returns { tools, partial }; partial: true means the inventory is incomplete: a source may be unavailable or some tools may have been omitted because of metadata problems. Listed tools remain callable subject to current permissions.
• permission is the current allow, ask, or deny decision; every call is judged again. Rules come from the user’s global tool permissions and permission mode, not a particular Agent or session. Host built-in tools retain their existing allowance, and Agent tool hooks do not run on this path.
• When confirmation is needed, the host prompts with Allow once, Always allow, and Deny. Only the user’s Always allow choice in that host prompt writes a global rule; the Mini App cannot answer it. When nobody can confirm, the call rejects with TOOL_APPROVAL_REQUIRED.
• MCP results contain kind: 'mcp', isError, and content; isError: true is a business failure reported by the tool, and the promise still resolves. Connector results contain kind: 'connector' and the raw value. Reconcile business state before retrying writes after unknown_after_dispatch.
• Node’s context.tool.request(names) and the page’s window.mcode.miniapp.tool.request(names) can ask for permission ahead of a call; feature-detect tool.request. A page request must come from a user gesture, name at most 10 tools, and have the Node service running. The page only requests permission; listing and calling stay in Node. Pass runtime names from Node to the page through your business API.

​

Host Connector

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

​

Decoding results

​

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.