Tools inside interactive apps

An HTML app opened in the Workspace preview or the ARIES embedded chat widget can expose tools that read its current state and update the visible interface. Use this for task boards, charts, document editors, and other interactive results.

Define app tools

In single-file HTML, import the frontend SDK in a module script from the pinned URL below. Workspace and ARIES previews only allow approved script URLs, so use it exactly as shown; no package install is needed. In a bundled app, install @botdojo/chat-sdk and import @botdojo/chat-sdk/frontend-mcp instead.

<script type="module">
import { registerFrontendMcp } from 'https://cdn.jsdelivr.net/npm/@botdojo/chat-sdk@0.0.31/lib/frontend-mcp/index.js';

const registration = await registerFrontendMcp({
  name: 'task_board',
  description: 'Read and update the visible task board',
  tools: [{
    name: 'get_board',
    description: 'Read the current tasks and selection',
    inputSchema: {
      type: 'object',
      properties: {},
      additionalProperties: false,
    },
    execute: async () => getCurrentBoard(),
  }, {
    name: 'move_task',
    description: 'Move a task to a column',
    inputSchema: {
      type: 'object',
      properties: {
        taskId: { type: 'string' },
        column: { type: 'string', enum: ['Todo', 'Doing', 'Done'] },
      },
      required: ['taskId', 'column'],
      additionalProperties: false,
    },
    execute: async ({ taskId, column }) => {
      moveTask(taskId, column);
      return getCurrentBoard();
    },
  }],
});
</script>

getCurrentBoard and moveTask are your app's own state functions. Handlers execute inside the preview and return JSON-serializable data. They require no API key or embedded chat. Read current state when a tool runs; for React apps, use current state references rather than capturing the first render.

Open and interact

1. Save the HTML file in the workspace, or create an MCP app artifact.
2. Open it in the Workspace preview, or follow its file link in ARIES, and wait for the app to finish registering. ARIES also supports MCP app cards and app artifacts in the conversation.
3. Ask the agent to read the app's state or invoke one of its actions.
4. Change the selection manually and ask again. The next call should reflect your current selection.

The host assigns unique tool names, so separate apps can both define get_board. Apps that are open when you send a message are available to the agent from the start of that turn. If the agent opens an app during a turn, it loads the app's tools then.

Definition updates

Use registration.update(nextModelContext) to replace tool definitions. Ordinary state changes do not require an update. Call registration.dispose() when explicitly removing the registration; closing the preview also cleans it up.

If an app already owns a McpAppClient, pass it as the second argument's client option to share the connection. Hosts without frontend MCP support return an unsupported-capability error.

Preview lifetime and saving

Tools are available while the app is mounted in its supported viewer. In ARIES, the message composer remains visible beneath an HTML app so you can ask the agent to use it. Returning to chat closes that file preview and removes its tools. Starting a new chat, switching conversations, or closing the widget revokes registrations from the previous session. An inline app card remains available while that card is mounted. Existing TeamConnect page tools remain available alongside app tools.

In Workspace, closing the preview, switching to HTML source, or opening another file can remove its tools. A background or scheduled agent cannot use a closed browser preview.

UI changes do not automatically save the HTML file or artifact. Add an explicit save operation using your app's existing authorized persistence behavior when durable changes are needed.

If a tool times out after it starts, it may already have changed the UI. Read the current state before deciding whether another action is necessary. The host does not automatically replay mutations after reconnecting.

Registrations belong to the current chat session and UI channel. Apps cannot select another conversation or workspace by supplying an ID. This support is enabled in Workspace and ARIES; other embed hosts must explicitly opt in through the shared host configuration.