MCP server elicitation

What elicitation is and what it's for

Standard MCP tool calls follow a one-shot pattern: the LLM sends tools/call with arguments, the server executes the tool, and the server returns a result. All information the tool needs must be present in the arguments at call time.

Elicitation adds a mid-call round trip. A tool handler can suspend execution, send a structured request to the host application, and receive the user's response before producing a result. This is different from tool approval (confirming an action before it runs) — elicitation collects information, not permission.

Valid use cases for elicitation:

• On-demand credentials — a file-sync tool discovers the remote requires a two-factor code it cannot store.
• Disambiguation — a search tool finds three records matching "Smith" and asks which one the user means.
• Missing required parameters — information that varies per-call and cannot be inferred from context (a recipient email address, a budget cap).
• User-controlled options — presenting a list of choices and letting the user pick (export format, notification frequency).

Use cases that should not use elicitation:

• Approval for destructive actions — use tool approval with a boolean confirmation schema instead.
• Information already derivable from context — if the LLM can infer the value from conversation history, it should pass it as a tool argument.
• Repeated data collection — credentials or preferences that should be stored as part of the session, not re-asked on every call.

Capability negotiation

Elicitation is an optional capability. Before calling requestElicitation, verify that the connected client supports it. The MCP SDK exposes this via the client capabilities object negotiated during initialize.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
    elicitation: {},  // declare that this server uses elicitation
  },
});

// In a tool handler, check before calling
server.tool('sync_files', { ... }, async (args, extra) => {
  const clientCapabilities = extra.clientCapabilities;

  if (!clientCapabilities?.elicitation) {
    // Client doesn't support elicitation — fall back or fail gracefully
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: 'This tool requires elicitation support. Use a client that supports MCP elicitation (e.g. Claude Desktop 1.6+) or provide the --two-factor-code argument directly.',
        }),
      }],
      isError: true,
    };
  }

  // Safe to elicit
  const result = await extra.requestElicitation({
    message: 'Enter your two-factor authentication code:',
    requestedSchema: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          title: 'Two-Factor Code',
          description: 'The 6-digit code from your authenticator app',
          pattern: '^[0-9]{6}$',
        },
      },
      required: ['code'],
    },
  });

  if (result.action !== 'accept') {
    return {
      content: [{ type: 'text', text: 'Sync cancelled — two-factor code not provided.' }],
      isError: false,
    };
  }

  const code = result.content.code as string;
  // proceed with sync
});

Elicitation schema design

The requestedSchema field takes a JSON Schema object. The host application renders a UI from this schema. Not all JSON Schema features are supported — stick to the subset that maps cleanly to form fields:

Keep schemas flat. Nested objects are valid JSON Schema but most host UIs render them poorly. If you need multiple fields, use a flat object with multiple top-level properties.

// Good: flat schema, clear field titles
const schema = {
  type: 'object',
  properties: {
    recipient: {
      type: 'string',
      title: 'Recipient email',
      format: 'email',
      description: 'The email address to send the report to',
    },
    format: {
      type: 'string',
      title: 'Export format',
      enum: ['pdf', 'csv', 'xlsx'],
      description: 'Choose the file format for the exported report',
    },
    include_drafts: {
      type: 'boolean',
      title: 'Include drafts',
      description: 'Include unpublished draft entries in the export',
    },
  },
  required: ['recipient', 'format'],
};

// Bad: nested schema — few hosts render this correctly
const badSchema = {
  type: 'object',
  properties: {
    destination: {
      type: 'object',
      properties: {
        email: { type: 'string' },
        name: { type: 'string' },
      },
    },
  },
};

Handling the three response actions

requestElicitation resolves to an object with an action field that is one of three values. Handle all three — do not assume the action will always be accept.

const result = await extra.requestElicitation({
  message: 'Which project should the task be added to?',
  requestedSchema: {
    type: 'object',
    properties: {
      project_id: {
        type: 'string',
        title: 'Project',
        enum: projectIds,
        description: 'Select the destination project',
      },
    },
    required: ['project_id'],
  },
});

switch (result.action) {
  case 'accept': {
    const projectId = result.content.project_id as string;
    await createTask(projectId, args.title);
    return { content: [{ type: 'text', text: `Task created in project ${projectId}.` }] };
  }
  case 'decline':
    return { content: [{ type: 'text', text: 'Task creation cancelled — no project selected.' }] };
  case 'cancel':
    return { content: [{ type: 'text', text: 'Task creation cancelled.' }] };
}

Retry loops for invalid input

JSON Schema validation in the host UI prevents structurally invalid input (wrong type, pattern mismatch). But semantic validation — checking that the entered ID actually exists, that the password is correct, that the date is in the future — has to happen in the tool handler. When semantic validation fails, you can elicit again.

const MAX_ATTEMPTS = 3;
let attempts = 0;
let lastError: string | null = null;

while (attempts < MAX_ATTEMPTS) {
  const message = lastError
    ? `${lastError} Please try again (attempt ${attempts + 1} of ${MAX_ATTEMPTS}):`
    : 'Enter your API key:';

  const result = await extra.requestElicitation({
    message,
    requestedSchema: {
      type: 'object',
      properties: {
        api_key: {
          type: 'string',
          title: 'API Key',
          format: 'password',
          minLength: 32,
        },
      },
      required: ['api_key'],
    },
  });

  if (result.action !== 'accept') {
    return { content: [{ type: 'text', text: 'Authentication cancelled.' }] };
  }

  const key = result.content.api_key as string;
  const valid = await validateApiKey(key);

  if (valid) {
    // proceed
    break;
  }

  lastError = 'That API key was not accepted.';
  attempts++;
}

if (attempts >= MAX_ATTEMPTS) {
  return {
    content: [{ type: 'text', text: 'Authentication failed after 3 attempts.' }],
    isError: true,
  };
}

Cap retry attempts. Unlimited retry loops frustrate users and can be abused. Three attempts is a reasonable default for credential entry; for simple choices, one is usually enough.

Elicitation vs prompt parameters

MCP has two other mechanisms for gathering user input: prompt parameters (defined in a PromptMessage via the Prompts API) and tool arguments. It's worth clarifying when each applies:

A common mistake is using elicitation to collect information that should be a tool argument — for example, always eliciting a "confirm?" prompt even when the LLM already knows the user wants to proceed. The LLM can pass confirmed: true as a tool argument when the user's intent is clear. Reserve elicitation for cases where the tool handler genuinely cannot proceed without user intervention that cannot be anticipated at call time.

Further reading

• MCP server tool approval — requiring human confirmation for destructive actions
• MCP server context propagation — threading user identity through tool calls
• MCP server tool design — naming, input schemas, and output formats
• MCP server Prompts API — templates, arguments, and embedded resources
• MCP server authentication — JWT, OAuth, and session-level identity
• AliveMCP — continuous protocol monitoring for MCP servers