Skip to main content

Workspace Widget

The Workspace Widget is a built-in MCP App that ships with io.Intelligence. It gives the AI assistant a visual canvas for workspace interactions — showing existing layouts before a user opens them, or providing an interactive editor when a user wants to build a brand-new workspace from scratch.

Built-In System Tool

The Workspace Widget replaces text descriptions of layouts with an interactive, visual workspace surface.

Instead of listing application names in chat, the assistant opens a live widget where users can see exactly what a workspace looks like — or drag and drop apps into the arrangement they want — before anything actually launches.

io.Assist Recommended

The Workspace Widget works with any MCP-compatible chat that supports the standard MCP UI extension. For the richest experience — including response-lock feedback, state persistence across thread switches, and smart close behavior — use io.Assist, which implements the full custom notification layer. See Custom Notifications for what third-party clients need to add.

Two Modes​

The widget operates in one of two modes, selected when the AI calls the tool.

Previewer Mode​

Previewer mode is read-only. The user sees an accurate visual representation of an existing workspace layout — the apps, their arrangement, and the tab structure — before deciding whether to open it.

When the AI uses it:

  • User asks to preview or review an existing workspace by name
  • AI wants to show the user what a workspace contains before launching it
  • Confirming what a search result looks like in practice

What the user can do:

  • Inspect the application arrangement visually
  • Read app names and layout structure
  • Decide whether to proceed with io_connect_start_workspace to actually open it

Builder Mode​

Builder mode is interactive. The user works on a visual canvas to arrange applications into a workspace before it is created. Apps can be dragged from a sidebar onto the canvas, split horizontally or vertically, stacked into tab groups, or placed at the canvas edges.

When the AI uses it:

  • User asks to create a new workspace with specific applications
  • AI has determined a component structure from the conversation and wants the user to review and possibly adjust it before launching
  • User wants an interactive surface to arrange apps themselves

What the user can do:

  • Drag apps from the sidebar onto the canvas
  • Split panes horizontally or vertically
  • Stack apps into tab groups
  • Place apps at full-height or full-width canvas edges
  • Refresh and reset the layout
  • Create the final workspace once satisfied

Display Modes​

The widget supports both inline and workspace display. The active display mode depends on the host application and availability of io.Connect workspaces.

Display ModeBehavior
InlineWidget renders inside the chat thread below the tool message
WorkspaceWidget opens as a standalone window beside the chat

In workspace mode, the widget and the chat can run side by side as first-class io.Connect windows. This is the recommended mode for the builder because it gives the canvas more room and supports the natural io.Connect workflow of building and then launching.

Custom Notifications​

The Workspace Widget uses all five io.Intelligence custom notifications. Any chat application that hosts the widget should implement these to get the full experience.

Response-Generation Status​

While the AI is processing a follow-up user message, the widget disables its interactive controls (drag-and-drop, buttons) automatically. This prevents the user from triggering workspace actions while the assistant is still working.

Host → Widget:

{
  "jsonrpc": "2.0",
  "method": "ui/notifications/response-generation-status",
  "params": { "isPending": true }
}

Widget behavior:

  • isPending: true → disable all buttons and drag interactions, show visual pulse on primary CTA
  • isPending: false → re-enable controls

Third-party host implementation:

// Send this notification when the AI starts or stops generating
function notifyResponseStatus(isPending) {
  appIframe.contentWindow.postMessage({
    jsonrpc: '2.0',
    method: 'ui/notifications/response-generation-status',
    params: { isPending },
  }, '*');
}

State Persistence​

The widget automatically saves its canvas state so users do not lose their work if they switch threads or reload the session.

Save State (Widget → Host)​

The widget sends this notification whenever the canvas layout changes:

{
  "jsonrpc": "2.0",
  "method": "ui/notifications/save-state",
  "params": {
    "state": { /* canvas layout object */ },
    "toolCallId": "tc-abc-123"
  }
}

Third-party host: Write the state object to durable storage keyed by toolCallId. Use the io Preferences API, localStorage, or your own backend.

Save State Response (Host → Widget)​

After writing the state, the host must confirm success or failure:

{
  "jsonrpc": "2.0",
  "method": "ui/notifications/save-state-response",
  "params": { "success": true }
}

If success is false, include an optional message string describing the error.

Load State (Host → Widget)​

When the widget initializes on a thread that has a saved state, the host sends it immediately after the app signals initialized:

{
  "jsonrpc": "2.0",
  "method": "ui/notifications/load-state",
  "params": { "state": { /* previously saved canvas layout */ } }
}

The widget restores its canvas to the saved state instead of starting fresh.

Third-party host: Look up the saved state by toolCallId when the widget initializes, then send this notification.

App Close (Widget → Host)​

When the user clicks "Create Workspace," the widget calls io_connect_start_workspace through the standard ui/call-tool bridge, then notifies the host that the job is done:

{
  "jsonrpc": "2.0",
  "method": "ui/notifications/close-ws-app",
  "params": {}
}

The host:

  1. Marks the app instance as "job done" in its state store (so it will not be reopened when the user switches back to this thread)
  2. In workspace mode: closes the widget window

Third-party host: When you receive close-ws-app for an app instance, mark it as complete in your persistence layer and perform any necessary UI cleanup (remove inline element, close window, etc.).

Server-Side Configuration​

The io_connect_get_workspace_widget tool is a system tool in @interopio/mcp-core. It is enabled by default when MCP Apps capability is detected. You can configure it through the server.tools.system.getWorkspaceWidget option:

server: {
  name: "my-mcp-server",
  tools: {
    system: {
      getWorkspaceWidget: {
        enabled: true,
        overrides: {
          name: "custom_workspace_widget",           // optional custom tool name
          description: "Custom workspace widget description",  // optional
        },
      },
    },
  },
}

The tool is only activated for MCP clients that advertise the io.modelcontextprotocol/ui extension with the text/html;profile=mcp-app MIME type. For clients that do not support MCP Apps, the tool is not registered.

For full tool input/output schema documentation, see Tool Types Reference.

Next Steps​