Skip to Content
onedef

Ask the user

ctx.elicitHumanInput shows a form in the client's own elicitation UI, and the workflow continues with the answer.

ctx.elicitHumanInput takes and returns what an MCP form elicitation does: message and requestedSchema in, { action, content } out.

import { createWorkflow } from '@onedef/elicitation-workflow'
import { z } from 'zod'

export const release = createWorkflow({ id: 'release', input: z.object({ version: z.string() }) }).handler(
  async (ctx) => {
    const build = await ctx.step('build', () => buildApp())   // runs once, whatever the user answers

    const answer = await ctx.elicitHumanInput({
      message: `Publish ${ctx.input.version} (${build.id})?`,
      requestedSchema: {
        type: 'object',
        properties: {
          channel: { type: 'string', enum: ['stable', 'beta'], title: 'Channel' },
          notes: { type: 'string', title: 'Release notes' },
        },
        required: ['channel'],
      },
    })

    if (answer.action !== 'accept') return { released: false }
    return ctx.step('ship', () => ship(build, answer.content?.channel))
  },
)

The answer

answer.action is what the user did:

actionmeaningcontent
acceptsubmitted the formthe fields
declinesaid nonone
canceldismissed it, or the client can't show formsnone

Every answer goes to your workflow, which decides what happens next. Nothing asks again in a loop.

The form

requestedSchema follows MCP's rules for elicitation forms: one flat object of primitive fields (string, number, boolean, enum). A submitted form missing a required field is rejected, and the run keeps waiting at the same question.

A run can ask several times. Each question gets a stable name from its position (elicit-1, elicit-2, …). Pass { id: 'confirm-release' } as a second argument to name it yourself.

What happens on the wire

When a run reaches the question, the tool returns MCP's input_required with the form and the run id as requestState. The client shows the form, then calls the same tool again with the answer. The run replays: finished steps return their recorded results, and the workflow continues right after the question.

On older (2025-era) connections, the MCP SDK sends the same form as an elicitation/create request. Your workflow doesn't change.

Testing with Claude Code

Headless claude -p cancels every form, because nobody is there to fill it in. To answer forms in a script, use an Elicitation hook:

answer.sh
#!/bin/bash
# Answers every form. Claude Code passes the form as JSON on stdin.
jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {channel: "beta"}}}'
settings.json
{ "hooks": { "Elicitation": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "./answer.sh" }] }] } }
claude -p "Release 2.1.0" --settings settings.json --mcp-config mcp.json --allowedTools "mcp__releases__*"

Also: yes-or-no approvals

TanStack Workflow's own ctx.approve works too. Over MCP it becomes a form with an Approve checkbox and an optional Feedback field:

const { approved, feedback } = await ctx.approve({ title: `Deploy ${build.id}?` })

Declining or dismissing that form counts as not approved. For anything beyond yes or no, use ctx.elicitHumanInput.

On this page