Two-way collaboration with the Agent

​

Three channels

​

Let the Agent call your Mini App: managed MCP

• Ordinary plugin MCP: runs independently (for example over stdio) without the Mini App’s Node service. Don’t list it in mcpEndpoints.
• Mini App-managed MCP: implemented by the Mini App’s Node service and available only while it runs. Use it when tools should share business state with the page.

{
  "schemaVersion": 1,
  "mcpServers": {
    "board-summary": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9/mcp/board-summary",
      "headers": {},
      "description": "Summarizes the current board data.",
      "timeout": 30000
    }
  }
}

{
  "mcpEndpoints": [
    { "server": "board-summary", "path": "/mcp/board-summary" }
  ]
}

• Before start returns, the Node entry must implement Streamable HTTP MCP at that path on context.listen. The host rewrites only this server’s address; tool discovery, ordering, calls, and errors stay with the plugin MCP runtime.
• When the user sends a message that references the Mini App, the host starts the service, connects MCP, and confirms the tools are available before calling the model. If a required managed MCP is unavailable, the request fails instead of letting the model continue without its tools.
• Keep tools/list light: return tool definitions only, without importing data, scanning documents, or calling remote services. Put business initialization in the tool calls that need it.
• A broken MCP handler doesn’t affect the page, but the Agent can’t use those tools until you fix it and publish again.

​

Hand off to the message input

​

Agent API

​

Enable it

{
  "agentAccess": ["session.run"],
  "agentConcurrency": 4
}

• Without agentAccess, access is denied. The only valid value is "session.run"; any other value is rejected at publish time with MINIAPP_AGENT_ACCESS_INVALID.
• agentConcurrency is optional, from 1 to 32, default 4: how many turns this Mini App runs at once. Extra calls wait in order, in a queue up to four times the concurrency. Each session runs one turn at a time.
• Grants take effect with the process: changing agentAccess and publishing again restarts the service.

​

Who owns a session

​

Methods

​

Approvals and questionnaires

• permission.requested → reply: a tool call waits for approval. Only “allow once” and “deny” exist; there is no “always allow”, because a Mini App never writes the user’s global permission rules.
• question.requested → answer: the turn paused on a questionnaire (ask_user, a feature enable, or a Plan review). Call answer after the paused run returns.
• An approval waits only while someone can answer it: the call passed onEvent, or a page has the session open in the sidebar through open. Otherwise it is denied, and the model is told that nobody can approve it and to continue without the tool.
• There is no timeout. A waiting call is released by cancellation, process exit, or republishing.
• When the Agent delegates to a child session, the child’s approvals also arrive through onEvent, with the child’s own sessionId. Don’t filter events by the root turn, or the call waits forever.

​

Page example

const agent = window.mcode?.miniapp?.agent;
if (agent) {
  const result = await agent.run(
    { text: 'Summarize this week\'s risks for the current filters and list what needs my confirmation.' },
    {
      onEvent(event) {
        if (event.type === 'text.delta') output.textContent += event.text;
        if (event.type === 'permission.requested') {
          // Render an approval card on the page; after the user decides, call:
          // agent.reply({ sessionId: event.sessionId, requestId: event.requestId, decision: 'allowOnce' })
          renderApproval(event);
        }
      },
    },
  );
  if (result.pendingQuestion) renderQuestionnaire(result.pendingQuestion.request);
  openInChatButton.onclick = () => agent.open(result.sessionId);
}

​

Node example

import type {
  MiniAppAgentClient,
  MiniAppAgentQuestionAnswer,
  MiniAppAgentQuestionnaire,
  MiniAppAgentRunEvent,
} from './miniapp-api.js';

// Your own UI round trips, for example an SSE push to the page and a POST back.
declare function askUser(request: MiniAppAgentQuestionnaire): Promise<MiniAppAgentQuestionAnswer[]>;
declare function confirmTool(toolName: string, reason: string): Promise<boolean>;

async function runWithQuestions(agent: MiniAppAgentClient, text: string) {
  const onEvent = (event: MiniAppAgentRunEvent) => {
    if (event.type !== 'permission.requested') return;
    // The run waits for this decision; the event names the session even on its first run.
    void confirmTool(event.toolName, event.reason)
      .then((allowed) =>
        agent.reply({
          sessionId: event.sessionId,
          requestId: event.requestId,
          decision: allowed ? 'allowOnce' : 'deny',
        }),
      )
      .catch(() => {}); // REQUEST_NOT_FOUND: the run was cancelled meanwhile.
  };
  let result = await agent.run({ text }, { onEvent });
  // Answer only after the run resolves: until then it holds the session's single-run slot.
  while (result.pendingQuestion) {
    const answers = await askUser(result.pendingQuestion.request);
    result = await agent.answer(
      { sessionId: result.sessionId, requestId: result.pendingQuestion.requestId, answers },
      { onEvent },
    );
  }
  return result;
}

​

Events

​

Design guidance

• Put the task, data scope, required interaction, success criteria, and stop conditions in text. Page labels, form state, and the host chat’s context aren’t carried over automatically.
• deny rejects only that one tool request; it doesn’t put the file off-limits from then on. Enforce boundaries that must hold across calls with host permissions or Hook rules.
• A root turn’s finished status doesn’t mean background child tasks are done. If you need a child’s result, use foreground delegation in the business request.
• AGENT_OUTCOME_UNKNOWN means the turn may already have run. Reconcile the session state first; don’t retry automatically.