|
| 1 | +--- |
| 2 | +title: Elicitation |
| 3 | +--- |
| 4 | + |
| 5 | +<Info>**Protocol Revision**: draft</Info> |
| 6 | + |
| 7 | +<Note> |
| 8 | +This version of the spec introduces the elicitation feature. It may change in future versions of the protocol. |
| 9 | +</Note> |
| 10 | + |
| 11 | +The Model Context Protocol (MCP) provides a standardized way for servers to request additional |
| 12 | +information from users through the client during interactions. This flow allows clients to |
| 13 | +maintain control over user interactions and data sharing while enabling servers to gather |
| 14 | +necessary information dynamically. |
| 15 | +Servers can request structured data from users with optional JSON schemas to validate responses. |
| 16 | + |
| 17 | +## User Interaction Model |
| 18 | + |
| 19 | +Elicitation in MCP allows servers to implement interactive workflows by enabling user input |
| 20 | +requests to occur _nested_ inside other MCP server features. |
| 21 | + |
| 22 | +Implementations are free to expose elicitation through any interface pattern that suits |
| 23 | +their needs—the protocol itself does not mandate any specific user interaction |
| 24 | +model. |
| 25 | + |
| 26 | +<Warning> |
| 27 | +For trust & safety and security: |
| 28 | + |
| 29 | +- Servers **MUST NOT** use elicitation to request sensitive information. |
| 30 | + |
| 31 | +Applications **SHOULD**: |
| 32 | + |
| 33 | +- Provide UI that makes it clear which server is requesting information |
| 34 | +- Allow users to review and modify their responses before sending |
| 35 | +- Respect user privacy and provide clear decline and cancel options |
| 36 | +</Warning> |
| 37 | + |
| 38 | +## Capabilities |
| 39 | + |
| 40 | +Clients that support elicitation **MUST** declare the `elicitation` capability during |
| 41 | +[initialization](/specification/draft/basic/lifecycle#initialization): |
| 42 | + |
| 43 | +```json |
| 44 | +{ |
| 45 | + "capabilities": { |
| 46 | + "elicitation": {} |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Protocol Messages |
| 52 | + |
| 53 | +### Creating Elicitation Requests |
| 54 | + |
| 55 | +To request information from a user, servers send an `elicitation/create` request: |
| 56 | + |
| 57 | +#### Simple Text Request |
| 58 | + |
| 59 | +**Request:** |
| 60 | + |
| 61 | +```json |
| 62 | +{ |
| 63 | + "jsonrpc": "2.0", |
| 64 | + "id": 1, |
| 65 | + "method": "elicitation/create", |
| 66 | + "params": { |
| 67 | + "message": "Please provide your GitHub username", |
| 68 | + "requestedSchema": { |
| 69 | + "type": "object", |
| 70 | + "properties": { |
| 71 | + "name": { |
| 72 | + "type": "string", |
| 73 | + }, |
| 74 | + }, |
| 75 | + "required": ["name"] |
| 76 | + } |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +**Response:** |
| 82 | + |
| 83 | +```json |
| 84 | +{ |
| 85 | + "jsonrpc": "2.0", |
| 86 | + "id": 1, |
| 87 | + "result": { |
| 88 | + "action": "accept", |
| 89 | + "content": { |
| 90 | + "name": "octocat" |
| 91 | + } |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +#### Structured Data Request |
| 97 | + |
| 98 | +**Request:** |
| 99 | + |
| 100 | +```json |
| 101 | +{ |
| 102 | + "jsonrpc": "2.0", |
| 103 | + "id": 2, |
| 104 | + "method": "elicitation/create", |
| 105 | + "params": { |
| 106 | + "message": "Please provide your contact information", |
| 107 | + "requestedSchema": { |
| 108 | + "type": "object", |
| 109 | + "properties": { |
| 110 | + "name": { |
| 111 | + "type": "string", |
| 112 | + "description": "Your full name" |
| 113 | + }, |
| 114 | + "email": { |
| 115 | + "type": "string", |
| 116 | + "format": "email", |
| 117 | + "description": "Your email address" |
| 118 | + }, |
| 119 | + "age": { |
| 120 | + "type": "number", |
| 121 | + "minimum": 18, |
| 122 | + "description": "Your age" |
| 123 | + } |
| 124 | + }, |
| 125 | + "required": ["name", "email"] |
| 126 | + } |
| 127 | + } |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +**Response:** |
| 132 | + |
| 133 | +```json |
| 134 | +{ |
| 135 | + "jsonrpc": "2.0", |
| 136 | + "id": 2, |
| 137 | + "result": { |
| 138 | + "action": "accept", |
| 139 | + "content": { |
| 140 | + "name": "Monalisa Octocat", |
| 141 | + |
| 142 | + "age": 30 |
| 143 | + } |
| 144 | + } |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +**Decline Response Example:** |
| 149 | + |
| 150 | +```json |
| 151 | +{ |
| 152 | + "jsonrpc": "2.0", |
| 153 | + "id": 2, |
| 154 | + "result": { |
| 155 | + "action": "decline" |
| 156 | + } |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +**Cancel Response Example:** |
| 161 | + |
| 162 | +```json |
| 163 | +{ |
| 164 | + "jsonrpc": "2.0", |
| 165 | + "id": 2, |
| 166 | + "result": { |
| 167 | + "action": "cancel" |
| 168 | + } |
| 169 | +} |
| 170 | +``` |
| 171 | + |
| 172 | +## Message Flow |
| 173 | + |
| 174 | +```mermaid |
| 175 | +sequenceDiagram |
| 176 | + participant Server |
| 177 | + participant Client |
| 178 | + participant User |
| 179 | + |
| 180 | + Note over Server,Client: Server initiates elicitation |
| 181 | + Server->>Client: elicitation/create |
| 182 | + |
| 183 | + Note over Client,User: Human interaction |
| 184 | + Client->>User: Present elicitation UI |
| 185 | + User-->>Client: Provide requested information |
| 186 | + |
| 187 | + Note over Server,Client: Complete request |
| 188 | + Client-->>Server: Return user response |
| 189 | + |
| 190 | + Note over Server: Continue processing with new information |
| 191 | +``` |
| 192 | + |
| 193 | +## Request Schema |
| 194 | + |
| 195 | +The `requestedSchema` field allows servers to define the structure of the expected response using a restricted subset of JSON Schema. To simplify implementation for clients, elicitation schemas are limited to flat objects with primitive properties only: |
| 196 | + |
| 197 | +```json |
| 198 | +"requestedSchema": { |
| 199 | + "type": "object", |
| 200 | + "properties": { |
| 201 | + "propertyName": { |
| 202 | + "type": "string", |
| 203 | + "title": "Display Name", |
| 204 | + "description": "Description of the property" |
| 205 | + }, |
| 206 | + "anotherProperty": { |
| 207 | + "type": "number", |
| 208 | + "minimum": 0, |
| 209 | + "maximum": 100 |
| 210 | + } |
| 211 | + }, |
| 212 | + "required": ["propertyName"] |
| 213 | +} |
| 214 | +``` |
| 215 | + |
| 216 | +### Supported Schema Types |
| 217 | + |
| 218 | +The schema is restricted to these primitive types: |
| 219 | + |
| 220 | +1. **String Schema** |
| 221 | + ```json |
| 222 | + { |
| 223 | + "type": "string", |
| 224 | + "title": "Display Name", |
| 225 | + "description": "Description text", |
| 226 | + "minLength": 3, |
| 227 | + "maxLength": 50, |
| 228 | + "pattern": "^[A-Za-z]+$", |
| 229 | + "format": "email" |
| 230 | + } |
| 231 | + ``` |
| 232 | + Supported formats: `email`, `uri`, `date`, `date-time` |
| 233 | + |
| 234 | +2. **Number Schema** |
| 235 | + ```json |
| 236 | + { |
| 237 | + "type": "number", // or "integer" |
| 238 | + "title": "Display Name", |
| 239 | + "description": "Description text", |
| 240 | + "minimum": 0, |
| 241 | + "maximum": 100 |
| 242 | + } |
| 243 | + ``` |
| 244 | + |
| 245 | +3. **Boolean Schema** |
| 246 | + ```json |
| 247 | + { |
| 248 | + "type": "boolean", |
| 249 | + "title": "Display Name", |
| 250 | + "description": "Description text", |
| 251 | + "default": false |
| 252 | + } |
| 253 | + ``` |
| 254 | + |
| 255 | +4. **Enum Schema** |
| 256 | + ```json |
| 257 | + { |
| 258 | + "type": "string", |
| 259 | + "title": "Display Name", |
| 260 | + "description": "Description text", |
| 261 | + "enum": ["option1", "option2", "option3"], |
| 262 | + "enumNames": ["Option 1", "Option 2", "Option 3"] |
| 263 | + } |
| 264 | + ``` |
| 265 | + |
| 266 | +Clients can use this schema to: |
| 267 | +1. Generate appropriate input forms |
| 268 | +2. Validate user input before sending |
| 269 | +3. Provide better guidance to users |
| 270 | + |
| 271 | +Note that complex nested structures, arrays of objects, and other advanced JSON Schema features are intentionally not supported to simplify client implementation. |
| 272 | + |
| 273 | +## Response Actions |
| 274 | + |
| 275 | +Elicitation responses use a three-action model to clearly distinguish between different user actions: |
| 276 | + |
| 277 | +```json |
| 278 | +{ |
| 279 | + "jsonrpc": "2.0", |
| 280 | + "id": 1, |
| 281 | + "result": { |
| 282 | + "action": "accept", // or "decline" or "cancel" |
| 283 | + "content": { |
| 284 | + "propertyName": "value", |
| 285 | + "anotherProperty": 42 |
| 286 | + } |
| 287 | + } |
| 288 | +} |
| 289 | +``` |
| 290 | + |
| 291 | +The three response actions are: |
| 292 | + |
| 293 | +1. **Accept** (`action: "accept"`): User explicitly approved and submitted with data |
| 294 | + - The `content` field contains the submitted data matching the requested schema |
| 295 | + - Example: User clicked "Submit", "OK", "Confirm", etc. |
| 296 | + |
| 297 | +2. **Decline** (`action: "decline"`): User explicitly rejected the request |
| 298 | + - The `content` field is typically omitted |
| 299 | + - Example: User clicked "Decline", "Reject", "No", etc. |
| 300 | + |
| 301 | +3. **Cancel** (`action: "cancel"`): User dismissed without making an explicit choice |
| 302 | + - The `content` field is typically omitted |
| 303 | + - Example: User closed the dialog, clicked outside, pressed Escape, etc. |
| 304 | + |
| 305 | +Servers should handle each state appropriately: |
| 306 | +- **Accept**: Process the submitted data |
| 307 | +- **Decline**: Handle explicit rejection (e.g., offer alternatives) |
| 308 | +- **Cancel**: Handle dismissal (e.g., prompt again later) |
| 309 | + |
| 310 | +## Security Considerations |
| 311 | + |
| 312 | +1. Servers **MUST NOT** request sensitive information through elicitation |
| 313 | +2. Clients **SHOULD** implement user approval controls |
| 314 | +3. Both parties **SHOULD** validate elicitation content against the provided schema |
| 315 | +4. Clients **SHOULD** provide clear indication of which server is requesting information |
| 316 | +5. Clients **SHOULD** allow users to reject elicitation requests at any time |
| 317 | +6. Clients **SHOULD** implement rate limiting |
| 318 | +7. Clients **SHOULD** present elicitation requests in a way that makes it clear what information is being requested and why |
0 commit comments