NextSteps Feature Documentation

NextSteps is a dynamic interaction feature that allows MCP (Model Context Protocol) servers to propose follow-up actions to users after tool execution. These proposals can be automatically executed after a countdown or manually selected by the user, enabling fluid conversational workflows and guided user experiences.

• Inline Pills: NextSteps appear as pill-shaped buttons within assistant messages
• Progress Indicators: Visual progress bars show countdown timers (auto) or priority levels (manual)
• Countdown Display: Numeric countdown badge shows remaining seconds for auto-execution
• Cancellation: User interaction (hover, click, typing) cancels auto-execution

1. Auto Execution: Proposals with type: "auto" automatically execute after countdown
2. Manual Selection: Proposals with type: "manual" require user click to execute
3. Priority Display: Manual proposals show static progress bars indicating relative priority

• Auto-Execution Toggle: Users can globally enable/disable auto-execution in settings
• Per-Result Override: Individual NextSteps can specify "auto" or "manual" regardless of global setting
• Cancellation: Any user interaction cancels pending auto-execution

MCP servers should return NextSteps data in their tool result's output.nextSteps field:

{
  "content": [
    {
      "type": "text", 
      "text": "{\"output\": {\"nextSteps\": {...}}}"
    }
  ]
}

interface NextStepsOutput {
  nextSteps: {
    type: "auto" | "manual";           // Execution mode
    priority?: number;                 // 0-100, higher = more priority
    countdown?: number;                // seconds for auto execution
    proposals: NextStepProposal[];     // Array of action proposals
  };
}

interface NextStepProposal {
  id: string;                         // Unique identifier
  title: string;                      // Display name (required)
  description?: string;               // Optional tooltip/subtitle
  action: {
    type: "send_message";             // Currently only message sending supported
    content: string;                  // Message content to send
  };
}

{
  "output": {
    "nextSteps": {
      "type": "auto",
      "countdown": 5,
      "proposals": [
        {
          "id": "continue_analysis",
          "title": "Continue Analysis",
          "description": "Analyze the next data segment",
          "action": {
            "type": "send_message",
            "content": "Please analyze the next segment of data using the same methodology."
          }
        }
      ]
    }
  }
}

{
  "output": {
    "nextSteps": {
      "type": "manual",
      "priority": 75,
      "proposals": [
        {
          "id": "save_results",
          "title": "Save Results",
          "description": "Save current analysis to file",
          "action": {
            "type": "send_message",
            "content": "Please save these results to a file named 'analysis_results.json'"
          }
        },
        {
          "id": "export_chart",
          "title": "Export Chart", 
          "description": "Generate visualization",
          "action": {
            "type": "send_message",
            "content": "Create a chart visualization of these results"
          }
        },
        {
          "id": "email_summary",
          "title": "Email Summary",
          "description": "Send summary via email",
          "action": {
            "type": "send_message", 
            "content": "Compose an email summary of this analysis for stakeholders"
          }
        }
      ]
    }
  }
}

{
  "output": {
    "nextSteps": {
      "type": "auto",
      "countdown": 10,
      "priority": 90,
      "proposals": [
        {
          "id": "retry_failed",
          "title": "Retry Failed Operations",
          "description": "Automatically retry the 3 failed operations",
          "action": {
            "type": "send_message",
            "content": "Retry the failed operations: upload_file, process_data, send_notification"
          }
        }
      ]
    }
  }
}

• Multi-step workflows: Guide users through complex processes
• Error recovery: Offer automatic retry or alternative approaches
• Data processing: Suggest next analysis steps or data transformations
• File operations: Propose saving, exporting, or sharing results
• Iterative tasks: Continue processing additional data segments

• Use "auto" for:
  • Obvious next steps in a workflow
  • Error recovery actions
  • Continuing interrupted processes
  • Time-sensitive operations
• Use "manual" for:
  • Destructive operations (delete, overwrite)
  • User preference decisions
  • Multiple valid alternatives
  • Final confirmation steps

• Short (3-5s): Obvious continuations, error retries
• Medium (5-10s): Workflow steps, data processing
• Long (10-15s): Complex operations, user review time
• No timeout: Use manual mode instead

• 90-100: Critical/urgent actions
• 70-89: Important workflow steps
• 50-69: Helpful suggestions
• 30-49: Optional enhancements
• 10-29: Nice-to-have actions

If NextSteps data is malformed, the client will:

1. Log a warning to console
2. Fall back to displaying the raw tool result
3. Continue normal operation

Servers should validate their NextSteps output to ensure:

• Required fields are present
• IDs are unique within the proposal set
• Countdown values are reasonable (1-60 seconds)
• Priority values are within 0-100 range

NextSteps works alongside existing MCP tool capabilities:

• HTML Output: Can be combined with output.html for rich displays
• File Operations: Suggest follow-up actions after file creation/modification
• API Calls: Propose next API operations or data processing steps
• Database Operations: Suggest queries, updates, or analysis steps

The NextSteps feature is implemented in the chat client with:

• Global auto-execution setting in user preferences
• Per-message override capability
• User interaction cancellation (hover, click, typing)
• Visual progress indicators and countdown timers
• Persistent storage of user preferences
• Mobile-responsive pill-based UI

Planned future capabilities:

• Action Types: Support for file downloads, API calls, tool execution
• Conditional Logic: Proposals based on user context or previous actions
• Scheduling: Delayed execution beyond immediate countdown
• Branching: Multiple workflow paths with decision points
• Templates: Reusable NextSteps patterns for common workflows

1. Create a tool that returns NextSteps in the specified format
2. Test both auto and manual execution modes
3. Verify countdown timers work correctly
4. Test user cancellation by interacting during countdown
5. Verify priority display for manual proposals

def create_test_nextsteps():
    return {
        "output": {
            "nextSteps": {
                "type": "auto",
                "countdown": 5,
                "proposals": [
                    {
                        "id": "test_action",
                        "title": "Test Action",
                        "description": "This is a test NextSteps proposal",
                        "action": {
                            "type": "send_message",
                            "content": "NextSteps test completed successfully!"
                        }
                    }
                ]
            }
        }
    }

• NextSteps object structure matches schema
• All required fields are present
• Proposal IDs are unique
• Countdown values are reasonable (1-60s)
• Priority values are 0-100
• Action content is meaningful
• Titles are concise and descriptive
• Descriptions provide helpful context

For questions about implementing NextSteps in your MCP server:

• Review the examples in this documentation
• Test with the provided validation checklist
• Check browser console for any parsing errors
• Ensure JSON structure exactly matches the schema

The NextSteps feature enhances user experience by providing intelligent workflow guidance while maintaining user control and preventing unwanted automatic actions.