tools that conditionally return ui resources

[robertyates]

First off the spec looks great and we are hoping to use parts of it in place of elicitations (which are very cumbersome to use).

For many of our use cases we want the tool to sometimes return a ui resources and sometimes just return to the model. I may be reading it wrong but it doesn't look like conditional rendering of ui resources in a tool response is possible at the moment, can you confirm? it looks as though every response from a tool with a ui resources MUST render that ui resources.

A simple use case that exhibits this would be transferring money - transfer_money(from (checking / savings), to (checking/savings, amount).

The code will enforce rules on ensuring that the user picks a different from and to and that the amount being transferred is less than the balance. None of this requires a widget. However for the final stage we would like to return a widget for confirmation. When the user clicks accept it calls a different tool to confirm the transfer.

Is this possible today? i.e. this conditional return of a ui resource or is it assumed that every time a tool (with a ui resource) is called that the ui resources must be rendered.

Thanks in advance.

[robertyates]

having looked at what openai does, i think that this response

    if (transferDate < today) {
      return {
        content: [{
          type: "text",
          text: "Cannot schedule a transfer in the past. Please specify today or a future date."
        }],
        isError: true
      };
    }

will cause the UI resource NOT to render as it has no structuredContent and isError set to true, can you confirm that this is how it should work and maybe update the spec to reflect this ?

[idosal]

Thanks @robertyates!

To optimize performance, the UI is rendered optimistically before the Tool responds. Hence, for the MVP, conditional rendering would mean optimistic rendering followed by termination as soon as the Tool responds. Currently, the MCP Apps spec doesn't include this mechanism, but we can add it if it's needed (potentially as part of the response's metadata).

As for Apps SDK, it has the openai/closeWidget functionality (see [docs]), but I'll defer to the folks from OpenAI for the best answer (@alexi-openai).

[robertyates]

Thanks, I assume others have these kinds of use cases, here's some sample code. How should something like this be best implemented ?

  // Check if date is in the past
    if (paymentDateObj < today) {
      // Note: No structuredContent is returned, so the UI widget will NOT be rendered.
      // This ensures validation errors are handled quickly without launching the widget.
      return {
        content: [
          {
            type: 'text',
            text: `We're unable to schedule a payment for ${paymentDate} as this date has already passed. Please select today's date or a date within the next 30 days.`,
            audience: ['user'],
          },
        ],
        isError: true,
      };
    }

    // Check if date is more than 30 days in the future
    if (paymentDateObj > thirtyDaysFromNow) {
      const latestDate = thirtyDaysFromNow.toISOString().split('T')[0];
      // Note: No structuredContent is returned, so the UI widget will NOT be rendered.
      // This ensures validation errors are handled quickly without launching the widget.
      return {
        content: [
          {
            type: 'text',
            text: `We can only schedule payments up to 30 days in advance. The date you selected (${paymentDate}) is beyond this window. Please choose a date on or before ${latestDate}.`,
            audience: ['user'],
          },
        ],
        isError: true,
      };
    }

    const loanNumber = `MTG-${customerId}-001`;
    const currentBalance = 287450.32;
    const transactionId = `TXN-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
    const expiresAt = new Date(Date.now() + 5 * 60 * 1000).toISOString(); // 5 minutes from now

    // Structured confirmation dialog format
    const confirmationDialog = {
      confirmationText: `## Confirm Mortgage Payment\n\nPlease review the payment details below and confirm to proceed:\n\n**Payment Details:**\n- **Loan Number:** ${loanNumber}\n- **Amount:** $${amount.toFixed(2)}\n- **Payment Date:** ${paymentDate}\n- **Current Balance:** $${currentBalance.toLocaleString()}\n\n**Transaction ID:** ${transactionId}\n\n⚠️ This transaction will expire in 5 minutes at ${new Date(expiresAt).toLocaleString()}`,
      confirmAction: {
        tool: 'confirm_or_cancel_mortgage_payment',
        parameters: {
          transactionId,
          action: 'confirm',
        },
      },
      cancelAction: {
        tool: 'confirm_or_cancel_mortgage_payment',
        parameters: {
          transactionId,
          action: 'cancel',
        },
      },
    };

    return {
      content: [
        {
          type: 'text',
          text: `A mortgage payment has been prepared with transaction ID ${transactionId}. The user will be presented with a confirmation dialog to review and approve the payment.`,
          audience: ['assistant'],
        },
      ],
      structuredContent: confirmationDialog,
    };
  },

We are looking to implement a host and so we can have a lazy load of the widget based on whether the structuredContent is present or not. We just want to make sure it's consistent with the spec.

[robertyates]

here's a concrete proposal, let me know if you'd be willing to accept a PR on this

MCP Apps Specification Proposal: Multiple Widget Support Per Tool

Overview

This document proposes an extension to the MCP Apps specification to support multiple UI widgets from a single tool.

Motivation

Problem Statement

The current MCP Apps specification allows tools to declare a single resourceUri for UI rendering. However, real-world business logic often requires different UI widgets at different stages of tool execution.

Use Case: Date Selection with Business Rules

Consider a money transfer tool that needs to:

1. Present a date picker with business-rule-constrained dates (e.g., "future dates only, but not more than 30 days out")
2. Show a confirmation screen with transfer details
3. Display a success message after completion

Why This Matters:

• Business rules for valid selections are often complex and context-dependent
• These rules are best enforced in the tool's business logic, not in generic UI components
• The tool needs to dynamically select which widget to display based on the current state

Current Limitation

With the current spec, a tool can only declare one UI resource:

{
  name: "visualize_data",
  _meta: {
    ui: {
      resourceUri: "ui://charts/bar-chart"  // ← Single URI only
    }
  }
}

This forces developers to either:

• Create overly complex, multi-purpose widgets
• Use multiple separate tools for what should be a single logical operation
• Implement business logic in the UI layer (violating separation of concerns)

Proposed Solution

1. Tool Registration Enhancement

Add a new resourceUris array to declare all possible widgets a tool may use:

{
  name: "transfer_money",
  _meta: {
    ui: {
      resourceUri: "ui://widgets/confirmation",  // ← Default/fallback
      resourceUris: [  // ← NEW: Array of possible widgets
        "ui://widgets/date-picker",
        "ui://widgets/confirmation",
        "ui://widgets/success"
      ]
    }
  }
}

Key Points:

• resourceUri remains as the default/fallback widget
• resourceUris declares all widgets the tool may use
• Backward compatible: existing tools without resourceUris continue to work

2. Dynamic Widget Selection in Tool Response

Tools can override the widget in their response:

// Tool response dynamically selects widget
{
  content: [...],
  structuredContent: {...},
  _meta: {
    ui: {
      resourceUri: "ui://widgets/date-picker"  // ← Override
    }
  }
}

3. Type Definitions

interface McpUiToolMeta {
  /** Default/fallback URI */
  resourceUri?: string;
  
  /** NEW: Array of possible UI resources this tool may use */
  resourceUris?: string[];
  
  visibility?: Array<"model" | "app">;
}

4. Validation Rules

1. Response Validation: If a tool response includes _meta.ui.resourceUri, it MUST be present in the declared resourceUris[] array
2. Fallback Behavior: If resourceUris is present but the response doesn't specify resourceUri, use the default resourceUri
3. Prefetching: Host applications SHOULD prefetch ALL URIs in resourceUris[] at connection time for optimal performance

Example Implementation

Complete Tool Registration

server.registerTool("transfer_money", {
  inputSchema: {
    from_account: z.string(),
    to_account: z.string(),
    amount: z.number(),
    transfer_date: z.string().optional()
  },
  _meta: {
    ui: {
      resourceUri: "ui://widgets/confirmation",  // Default
      resourceUris: [
        "ui://widgets/date-picker",
        "ui://widgets/confirmation", 
        "ui://widgets/success"
      ]
    }
  }
}, async ({ from_account, to_account, amount, transfer_date }) => {
  // Stage 1: Date selection with business rules
  if (!transfer_date) {
    return {
      content: [{ type: "text", text: "Select transfer date" }],
      structuredContent: { 
        validDateRange: { 
          min: today(), 
          max: thirtyDaysOut() 
        }
      },
      _meta: {
        ui: {
          resourceUri: "ui://widgets/date-picker"
        }
      }
    };
  }
  
  // Stage 2: Confirmation
  return {
    content: [{ type: "text", text: "Confirm transfer" }],
    structuredContent: { 
      from_account, 
      to_account, 
      amount, 
      transfer_date 
    },
    _meta: {
      ui: {
        resourceUri: "ui://widgets/confirmation"
      }
    }
  };
});

Flow Diagram

User Request → Tool Invoked (no date)
                ↓
            Returns date-picker widget
            with business rules (min/max dates)
                ↓
User Selects Date → Tool Invoked (with date)
                ↓
            Returns confirmation widget
            with transfer details
                ↓
User Confirms → Tool Executes Transfer
                ↓
            Returns success widget

Benefits

1. Separation of Concerns: Business logic stays in the tool, UI stays in widgets
2. Reusable Widgets: Generic widgets (date-picker, confirmation) can be reused across tools
3. Dynamic UX: Tools can adapt their UI based on state and business rules
4. Backward Compatible: Existing tools continue to work without changes
5. Performance: Hosts can prefetch all possible widgets at connection time

Migration Path

For Existing Tools

No changes required. Tools with only resourceUri continue to work as before.

For New Tools

1. Declare all possible widgets in resourceUris[]
2. Set a sensible default in resourceUri
3. Return appropriate resourceUri in tool responses based on state

For Host Applications

1. Support both resourceUri (existing) and resourceUris[] (new)
2. Implement validation: response URIs must be in declared array
3. Consider prefetching all declared URIs for better performance