[feat] Introduce elcitation as new client capability

Author: Abhimanyu Siwach

docs/docs.json

@@ -46,6 +46,7 @@
               "docs/concepts/prompts",
               "docs/concepts/tools",
               "docs/concepts/sampling",
+              "docs/concepts/elicitation",
               "docs/concepts/roots",
               "docs/concepts/transports"
             ]
@@ -105,7 +106,8 @@
                 "group": "Client Features",
                 "pages": [
                   "specification/2025-03-26/client/roots",
-                  "specification/2025-03-26/client/sampling"
+                  "specification/2025-03-26/client/sampling",
+                  "specification/2025-03-26/client/elicitation"
                 ]
               },
               {

docs/docs/concepts/elicitation.mdx

@@ -0,0 +1,200 @@
+---
+title: "Elicitation"
+description: "Let your servers request additional information from users"
+---
+
+Elicitation is a powerful MCP feature that allows servers to request additional information directly from users through the client, enabling interactive workflows while maintaining security and privacy controls.
+
+<Info>
+  This feature of MCP is not yet supported in the Claude Desktop client.
+</Info>
+
+## How elicitation works
+
+The elicitation flow follows these steps:
+
+1. Server sends an `elicitation/create` request to the client
+2. Client presents the request to the user
+3. User provides the requested information
+4. Client reviews and can modify the response
+5. Client returns the result to the server
+
+This human-in-the-loop design ensures users maintain control over what information they share with servers.
+
+## Message format
+
+Elicitation requests use a standardized message format:
+
+```typescript
+{
+  message: string
+}
+```
+
+The response format is:
+
+```typescript
+{
+  content: [
+    {
+      type: "text" | "image" | "audio",
+      
+      // For text:
+      text?: string,
+      
+      // For images:
+      data?: string,             // base64 encoded
+      mimeType?: string,
+      
+      // For audio:
+      data?: string,             // base64 encoded
+      mimeType?: string
+    },
+    // Additional content items...
+  ],
+  cancelled?: boolean
+}
+```
+
+## Request parameters
+
+### Message
+
+The `message` field contains the text prompt to present to the user, explaining what information is being requested and why.
+
+## Response format
+
+The client returns an elicitation result with:
+
+- `content`: An array of the user's responses, which can include:
+  - Text content with a `text` field
+  - Image content with `data` (base64) and `mimeType` fields
+  - Audio content with `data` (base64) and `mimeType` fields
+- `cancelled`: Optional boolean indicating if the user cancelled the request
+
+The content array allows clients to return multiple response items of different types, such as text with an accompanying image.
+
+## Example requests
+
+### Basic elicitation
+
+```json
+{
+  "method": "elicitation/create",
+  "params": {
+    "message": "What is your favorite programming language?"
+  }
+}
+```
+
+### Example response with multiple content items
+
+```json
+{
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Python"
+      },
+      {
+        "type": "image",
+        "data": "base64-encoded-image-data",
+        "mimeType": "image/png"
+      }
+    ]
+  }
+}
+```
+
+## Best practices
+
+When implementing elicitation:
+
+1. Provide clear, concise messages explaining what information is needed and why
+2. Only request information that is necessary for the task
+3. Handle all response types appropriately (text, image, audio)
+4. Respect user privacy and data minimization principles
+5. Consider returning multiple content items when appropriate
+7. Validate responses before using them
+8. Handle cancellations gracefully
+9. Consider progressive disclosure for complex information requests
+10. Document expected elicitation behavior
+
+## Human in the loop controls
+
+Elicitation is designed with user agency in mind:
+
+### For requests
+
+- Clients should clearly show which server is requesting information
+- Users should be able to modify or reject requests
+- Clients can filter or block inappropriate requests
+- Users should understand why the information is being requested
+
+### For responses
+
+- Users should be able to review their responses before sending
+- Clients should provide clear UI for structured data input
+- Users should be able to cancel requests at any time
+- Clients can sanitize or modify responses to protect privacy
+
+## Security considerations
+
+When implementing elicitation:
+
+- Validate all message content
+- Sanitize sensitive information
+- Implement appropriate rate limits
+- Monitor elicitation usage
+- Encrypt data in transit
+- Handle user data privacy
+- Audit elicitation requests
+- Implement timeouts
+- Provide clear privacy policies
+- Allow users to opt out
+
+## Common patterns
+
+### Interactive workflows
+
+Elicitation enables interactive patterns like:
+
+- Progressive form filling
+- Multi-step data collection
+- Contextual information gathering
+- Clarification of ambiguous requests
+- Confirmation of critical actions
+
+### Multiple content items
+
+Best practices for handling multiple content items:
+
+- Consider when multiple items enhance the response
+- Organize content items in a logical order
+- Handle cases where clients may only support a subset of content types
+- Validate each content item individually
+
+### Error handling
+
+Robust error handling should:
+
+- Catch validation failures
+- Handle timeout errors
+- Manage rate limits
+- Provide helpful error messages
+- Support retries when appropriate
+- Log errors appropriately
+
+## Limitations
+
+Be aware of these limitations:
+
+- Elicitation depends on client capabilities
+- Not all clients support multiple content items
+- Users control what information they provide
+- Response formats may be limited
+- Rate limits may apply
+- User experience varies by client
+- Response times depend on user interaction
+- Not all content types may be supported by all clients

docs/specification/2025-03-26/changelog.mdx

@@ -18,13 +18,17 @@ the previous revision, [2024-11-05](/specification/2024-11-05).
 1. Added comprehensive **tool annotations** for better describing tool behavior, like
    whether it is read-only or destructive (PR
    [#185](https://github.com/modelcontextprotocol/specification/pull/185))
+1. Added support for **[elicitation](/specification/2025-03-26/client/elicitation)**, enabling
+   servers to request additional information from users during interactions
 
 ## Other schema changes
 
 - Added `message` field to `ProgressNotification` to provide descriptive status updates
 - Added support for audio data, joining the existing text and image content types
 - Added `completions` capability to explicitly indicate support for argument
   autocompletion suggestions
+- Added `elicitation` capability for clients to indicate support for server-initiated
+  user information requests with array-based responses
 
 See
 [the updated schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2025-03-26/schema.ts)