Skip to main content
View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/utils/elicitation-helpers.ts
Elicitation schema helpers (SEP-1330). These helpers generate JSON Schema fragments for enum-style elicitation fields. They are intended for use with the verbose ctx.elicit({ requestedSchema }) API, where you pass a raw MCP elicitation schema instead of a Zod object. Each function is a pure builder: it takes plain arrays of values or options and returns a JSON Schema fragment object. None of them throw, none mutate their inputs (value arrays are copied), and there are no defaults or hidden limits. Compose field builders into a top-level object schema with enumSchema, then pass it as requestedSchema. All functions and types on this page are exported from mcp-use/server. 
import {
  enumSchema,
  untitledEnum,
  titledEnum,
  legacyEnum,
  untitledMultiEnum,
  titledMultiEnum,
} from "mcp-use/server";
The example below sets up a server using new MCPServer({ ... }) and uses these helpers to build a requestedSchema passed to the verbose ctx.elicit call. 
import { error, MCPServer, text, enumSchema, titledEnum, untitledMultiEnum } from "mcp-use/server";

const server = new MCPServer({
  name: "elicitation-example-server",
  version: "1.0.0",
  description: "An MCP server example demonstrating elicitation capabilities",
});

server.tool(
  {
    name: "pick-options",
    description: "Collect a plan and feature selection via enum elicitation.",
  },
  async (params, ctx) => {
    const requestedSchema = enumSchema({
      plan: titledEnum([
        { value: "free", title: "Free" },
        { value: "pro", title: "Pro" },
      ]),
      features: untitledMultiEnum(["analytics", "exports", "sso"]),
    });

    const result = await ctx.elicit({
      message: "Choose your plan and features",
      requestedSchema,
    });

    if (result.action === "accept") {
      return text(`Received: ${JSON.stringify(result.data)}`);
    }
    return error("User declined or cancelled");
  }
);

await server.listen();

​
Functions

​
enumSchema

Build a top-level object schema for an elicitation requestedSchema. 
import { enumSchema } from "mcp-use/server";
Wraps a map of field names to enum field schemas into a single object schema suitable for the requestedSchema argument of the verbose ctx.elicit call. The returned object always has type: "object" and its properties is exactly the fields map you pass in (it is assigned by reference, not copied). Pass an empty object to produce a schema with no properties. The values you supply should be built with the field helpers below (untitledEnum, titledEnum, legacyEnum, untitledMultiEnum, titledMultiEnum). Parameters
​
fields
Record<string, ElicitationEnumFieldSchema>
required
Map of field name to enum field schema. See ElicitationEnumFieldSchema.
Returns
​
returns
ElicitationEnumObjectSchema
Object schema with type: “object” and the given properties. See ElicitationEnumObjectSchema.
Signature 
function enumSchema(fields: Record<string, ElicitationEnumFieldSchema>): ElicitationEnumObjectSchema

​
untitledEnum

Build an untitled single-select enum field schema. 
import { untitledEnum } from "mcp-use/server";
Produces a single-select string enum with no display titles, where the raw values are shown to the user. The returned schema has type: "string" and an enum array. The values array is shallow-copied into the result (via [...values]), so later mutation of the input does not affect the returned schema. An empty values array yields { type: "string", enum: [] }. The result is an example of { type: "string", enum: ["a", "b"] }. Parameters
​
values
string[]
required
The allowed string values for the single-select enum.
Returns
​
returns
UntitledEnumSchema
See UntitledEnumSchema.
Signature 
function untitledEnum(values: string[]): UntitledEnumSchema

​
titledEnum

Build a titled single-select enum field schema. 
import { titledEnum } from "mcp-use/server";
Produces a single-select string enum with human-readable display titles. The returned schema has type: "string" and a oneOf array, where each entry is mapped from an option to { const: option.value, title: option.title }. This is the recommended titled form under SEP-1330 (prefer it over legacyEnum). An empty options array yields an empty oneOf. The result is an example of { type: "string", oneOf: [{ const: "a", title: "Option A" }] }. Parameters
​
options
EnumOption[]
required
Options with value and title. See EnumOption.
Returns
​
returns
TitledEnumSchema
See TitledEnumSchema.
Signature 
function titledEnum(options: EnumOption[]): TitledEnumSchema

​
legacyEnum

Build a legacy titled single-select enum field schema. 
import { legacyEnum } from "mcp-use/server";
Produces a single-select string enum using the legacy enum plus enumNames form. This form is deprecated in SEP-1330 but still supported, prefer titledEnum for new code. The returned schema has type: "string", an enum array mapped from option.value, and an enumNames array mapped from option.name (positionally aligned). An empty options array yields empty enum and enumNames arrays. The result is an example of { type: "string", enum: ["a"], enumNames: ["Option A"] }. Parameters
​
options
LegacyEnumOption[]
required
Options with value and name. See LegacyEnumOption.
Returns
​
returns
LegacyEnumSchema
See LegacyEnumSchema.
Signature 
function legacyEnum(options: LegacyEnumOption[]): LegacyEnumSchema

​
untitledMultiEnum

Build an untitled multi-select enum field schema. 
import { untitledMultiEnum } from "mcp-use/server";
Produces a multi-select (array) enum with no display titles. The returned schema has type: "array" and items set to { type: "string", enum: [...values] }, so the values array is shallow-copied into items.enum and later mutation of the input does not affect the result. An empty values array yields items with an empty enum. The result is an example of { type: "array", items: { type: "string", enum: ["a", "b"] } }. Parameters
​
values
string[]
required
The allowed string values for the multi-select enum.
Returns
​
returns
UntitledMultiEnumSchema
See UntitledMultiEnumSchema.
Signature 
function untitledMultiEnum(values: string[]): UntitledMultiEnumSchema

​
titledMultiEnum

Build a titled multi-select enum field schema. 
import { titledMultiEnum } from "mcp-use/server";
Produces a multi-select (array) enum with human-readable display titles. The returned schema has type: "array" and items set to { anyOf: [...] }, where each entry is mapped from an option to { const: option.value, title: option.title }. An empty options array yields items with an empty anyOf. The result is an example of { type: "array", items: { anyOf: [{ const: "a", title: "Option A" }] } }. Parameters
​
options
EnumOption[]
required
Options with value and title. See EnumOption.
Returns
​
returns
TitledMultiEnumSchema
See TitledMultiEnumSchema.
Signature 
function titledMultiEnum(options: EnumOption[]): TitledMultiEnumSchema

​
Types

​
EnumOption

A single titled enum option used by titledEnum and titledMultiEnum. 
import type { EnumOption } from "mcp-use/server";
Describes one option of a titled enum: the underlying machine value and the human-readable display title. Used as the element type of the options argument to titledEnum and titledMultiEnum. Properties
​
value
string
required
The underlying value sent back when this option is selected.
​
title
string
required
The human-readable display title for this option.
Definition 
interface EnumOption {
  value: string;
  title: string;
}

​
LegacyEnumOption

A single titled enum option used by legacyEnum. 
import type { LegacyEnumOption } from "mcp-use/server";
Describes one option for the legacy enum plus enumNames form. It is identical to EnumOption except the display label field is named name instead of title. Used as the element type of the options argument to legacyEnum. Properties
​
value
string
required
The underlying value sent back when this option is selected.
​
name
string
required
The human-readable display label for this option.
Definition 
interface LegacyEnumOption {
  value: string;
  name: string;
}

​
UntitledEnumSchema

JSON Schema fragment for an untitled single-select enum. 
import type { UntitledEnumSchema } from "mcp-use/server";
The return type of untitledEnum. Represents a single-select string field whose allowed values are listed directly in enum, with no separate display titles. Properties
​
type
"string"
required
Always the literal “string”.
​
enum
string[]
required
The allowed string values.
Definition 
interface UntitledEnumSchema {
  type: "string";
  enum: string[];
}

​
TitledEnumSchema

JSON Schema fragment for a titled single-select enum. 
import type { TitledEnumSchema } from "mcp-use/server";
The return type of titledEnum. Represents a single-select string field where each allowed value carries a display title, expressed as a oneOf array of { const, title } entries. Properties
​
type
"string"
required
Always the literal “string”.
​
oneOf
Array<{ const: string; title: string }>
required
One entry per allowed value, each with a const value and a title.
Definition 
interface TitledEnumSchema {
  type: "string";
  oneOf: Array<{ const: string; title: string }>;
}

​
LegacyEnumSchema

JSON Schema fragment for a legacy titled single-select enum. 
import type { LegacyEnumSchema } from "mcp-use/server";
The return type of legacyEnum. Represents a single-select string field using the deprecated enum plus enumNames form, where enum[i] is the value and enumNames[i] is its display label. Properties
​
type
"string"
required
Always the literal “string”.
​
enum
string[]
required
The allowed string values.
​
enumNames
string[]
required
Display labels, positionally aligned with enum.
Definition 
interface LegacyEnumSchema {
  type: "string";
  enum: string[];
  enumNames: string[];
}

​
UntitledMultiEnumSchema

JSON Schema fragment for an untitled multi-select enum. 
import type { UntitledMultiEnumSchema } from "mcp-use/server";
The return type of untitledMultiEnum. Represents a multi-select (array) field whose items are a single-select string enum with no display titles. Properties
​
type
"array"
required
Always the literal “array”.
​
items
{ type: "string"; enum: string[] }
required
The item schema: a string enum of allowed values.
Definition 
interface UntitledMultiEnumSchema {
  type: "array";
  items: {
    type: "string";
    enum: string[];
  };
}

​
TitledMultiEnumSchema

JSON Schema fragment for a titled multi-select enum. 
import type { TitledMultiEnumSchema } from "mcp-use/server";
The return type of titledMultiEnum. Represents a multi-select (array) field whose items carry display titles, expressed as an anyOf array of { const, title } entries. Properties
​
type
"array"
required
Always the literal “array”.
​
items
{ anyOf: Array<{ const: string; title: string }> }
required
The item schema: an anyOf of titled const entries.
Definition 
interface TitledMultiEnumSchema {
  type: "array";
  items: {
    anyOf: Array<{ const: string; title: string }>;
  };
}

​
ElicitationEnumFieldSchema

Union of every enum field schema produced by the field helpers. 
import type { ElicitationEnumFieldSchema } from "mcp-use/server";
A discriminated union of all enum field schema shapes that can appear as a property in an elicitation object schema. It is the value type of the fields argument to enumSchema and of properties in ElicitationEnumObjectSchema. Each member is the return type of one field helper above. Definition 
type ElicitationEnumFieldSchema =
  | UntitledEnumSchema
  | TitledEnumSchema
  | LegacyEnumSchema
  | UntitledMultiEnumSchema
  | TitledMultiEnumSchema;

​
ElicitationEnumObjectSchema

Top-level object schema returned by enumSchema. 
import type { ElicitationEnumObjectSchema } from "mcp-use/server";
The return type of enumSchema. Represents the top-level object schema you pass as requestedSchema to the verbose ctx.elicit call, mapping each field name to an ElicitationEnumFieldSchema. Properties
​
type
"object"
required
Always the literal “object”.
​
properties
Record<string, ElicitationEnumFieldSchema>
required
Map of field name to enum field schema.
Definition 
interface ElicitationEnumObjectSchema {
  type: "object";
  properties: Record<string, ElicitationEnumFieldSchema>;
}