Elicitation

Elicitation lets a tool return an input_required result. A capable client collects input and retries the original tool call; the callback runs again with the response in its request context. Use form mode for ordinary structured input and URL mode when values must stay on an external site.

Handle the input-required round

Every call has a stable correlation key, a user-facing message, and either a Standard Schema form schema or a URL:

import {
  acceptedContent,
  inputRequired,
  inputResponse,
  MCPServer,
} from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "deployment-server",
  version: "1.0.0",
});

const approvalSchema = z.object({
  approve: z.boolean().describe("Approve this deployment"),
  note: z.string().max(200).optional(),
});

server.tool(
  {
    name: "deploy",
    inputSchema: z.object({
      environment: z.enum(["staging", "production"]),
    }),
    outputSchema: z.object({
      environment: z.string(),
      deployed: z.boolean(),
    }),
  },
  async ({ environment }, ctx) => {
    // A stateless handler starts from the top on both the initial call and
    // every retry. Inspect this round's response before deciding to ask again.
    const response = inputResponse(ctx.inputResponses, "deployment-approval");
    if (response.kind === "elicit" && response.action !== "accept") {
      return {
        isError: true,
        content: [{ type: "text", text: "Deployment was not approved." }],
      };
    }

    const confirmation = acceptedContent(
      ctx.inputResponses,
      "deployment-approval",
      approvalSchema,
    );
    // Missing or invalid accepted content means this invocation still needs
    // input, so return input_required instead of continuing.
    if (confirmation === undefined) {
      return inputRequired({
        inputRequests: {
          "deployment-approval": inputRequired.elicit({
            message: `Deploy to ${environment}?`,
            requestedSchema: approvalSchema,
          }),
        },
      });
    }

    if (!confirmation.approve) {
      return {
        isError: true,
        content: [{ type: "text", text: "Deployment was not approved." }],
      };
    }

    // Side effects belong after accepted, validated input because every
    // input_required round invokes this callback again from the beginning.
    await deployments.start(environment, confirmation.note);

    const data = { environment, deployed: true };
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      structuredContent: data,
    };
  },
);

export default server;

The stable key correlates the embedded request with the matching value in ctx.inputResponses. inputResponse() reads that response for you, and acceptedContent() validates accepted form data against the schema. Missing or invalid accepted content makes acceptedContent() return undefined, so the handler returns another input_required round. For an elicitation key, inputResponse() returns one of these. The full union also carries kind: "roots" and kind: "sampling" for the other request types:

Response	Meaning
`kind: "missing"`	No response for this key yet, so return another `input_required` round
`kind: "elicit"`, `action: "accept"`	The user submitted; in form mode read it with `acceptedContent()`, URL mode carries no form data
`kind: "elicit"`, `action: "decline"`	The user explicitly refused
`kind: "elicit"`, `action: "cancel"`	The user dismissed or interrupted the flow

Form mode

Form mode accepts a Standard Schema that can be converted to JSON Schema. Keep forms flat and use primitive fields, enums, and arrays of enum values. Add descriptions and refinements before passing the schema to inputRequired.elicit(). Do not collect passwords, API keys, payment details, or OAuth secrets in form mode. Submitted form values pass through the MCP client.

URL mode

Pass the absolute URL to inputRequired.elicitUrl() instead of a schema. Keep the external flow’s state in a trusted backend and look it up with a stable, unguessable handle from the original tool input:

const flow = await githubAuth.getOrCreateFlow(connectionId);

// This is either the initial call (missing) or a fresh retry. Resolve the
// retry response first; only the missing case should request input.
const response = inputResponse(ctx.inputResponses, "github-authorization");
if (response.kind === "elicit" && response.action !== "accept") {
  return {
    isError: true,
    content: [{ type: "text", text: "Authorization was not completed." }],
  };
}

if (response.kind !== "elicit") {
  return inputRequired({
    inputRequests: {
      "github-authorization": inputRequired.elicitUrl({
        message: "Authorize GitHub access",
        url: flow.authorizationUrl,
      }),
    },
  });
}

const connection = await githubAuth.requireCompleted(flow.id);

URL mode asks the client to open an external flow; it does not return secrets or prove that the flow succeeded. getOrCreateFlow must return the same server-stored flow when the callback reruns with connectionId. Verify callback state and completion on your own backend before performing a protected action.

Keep multi-round workflows safe

Because the callback re-runs for each input-required round:

Perform reads and validation before elicitation as needed.
Perform irreversible side effects only after the relevant accept.
Use a different stable key for each distinct question.
Use verified requestState when a multi-step workflow needs trusted state.
Treat bare ctx.inputResponses as untrusted client input if you read it directly.

Run and test the example

cd libraries/typescript/packages/server/examples/elicitation
pnpm dev

Connect a client that supports form and URL elicitation to http://localhost:3000/mcp. Test accept, decline, cancel, an invalid form response that triggers another round, and the URL callback-verification path.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Handle the input-required round

Form mode

URL mode

Keep multi-round workflows safe

Run and test the example

​Handle the input-required round

​Form mode

​URL mode

​Keep multi-round workflows safe

​Run and test the example

Handle the input-required round

Form mode

URL mode

Keep multi-round workflows safe

Run and test the example