Skip to content

Commit 23b0d7e

Browse files
saqadrisaqadri
committed
Add elicitation docs to concepts, and also address PR feedback
1 parent 5927e85 commit 23b0d7e

File tree

3 files changed

+245
-1
lines changed

3 files changed

+245
-1
lines changed

‎docs/clients.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This page provides an overview of applications that support the Model Context Pr
1111

1212
{/* prettier-ignore-start */}
1313

14-
| Client | [Resources] | [Prompts] | [Tools] | [Discovery] | [Sampling] | [Roots] | [Elicitation](specification/2025-06-18/client/elicitation) | Notes |
14+
| Client | [Resources] | [Prompts] | [Tools] | [Discovery] | [Sampling] | [Roots] | [Elicitation] | Notes |
1515
| ------------------------------------------------ | ----------- | --------- | ------- | ---------------------- | ---------- | ----- | ------------ | ----------------------------------------------------------------------------------------------- |
1616
| [5ire][5ire] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | Supports tools. |
1717
| [AgentAI][AgentAI] | ❌ | ❌ | ✅ | ❓ | ❌ | ❌ | ❓ | Agent Library written in Rust with tools support |
@@ -92,6 +92,7 @@ This page provides an overview of applications that support the Model Context Pr
9292
[Discovery]: /docs/concepts/tools#tool-discovery-and-updates
9393
[Sampling]: /docs/concepts/sampling
9494
[Roots]: /docs/concepts/roots
95+
[Elicitation]: /docs/concepts/elicitation
9596
[5ire]: https://github.com/nanbingxyz/5ire
9697
[AgentAI]: https://github.com/AdamStrojek/rust-agentai
9798
[AgenticFlow]: https://agenticflow.ai/mcp

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
"docs/concepts/tools",
4343
"docs/concepts/sampling",
4444
"docs/concepts/roots",
45+
"docs/concepts/elicitation",
4546
"docs/concepts/transports"
4647
]
4748
},

‎docs/docs/concepts/elicitation.mdx‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: "Elicitation"
3+
description: "Interactive information gathering in MCP"
4+
---
5+
6+
Elicitation is a powerful MCP feature that allows servers to request additional information from users during interactions. This enables dynamic workflows where servers can gather necessary data on-demand while maintaining user control and privacy.
7+
8+
<Info>
9+
Elicitation is newly introduced in the MCP specification [revision
10+
2025-06-18](/specification/2025-06-18/client/elicitation).
11+
</Info>
12+
13+
## What is Elicitation?
14+
15+
Elicitation provides a standardized way for MCP servers to request structured information from users through the client. Instead of requiring all information upfront, servers can ask for specific data exactly when needed, creating more natural and flexible interactions.
16+
17+
For example, a server might:
18+
19+
- Request a username when connecting to a service
20+
- Ask for configuration preferences during setup
21+
- Gather project details when creating new resources
22+
23+
## How Elicitation Works
24+
25+
The elicitation flow is straightforward:
26+
27+
1. Server sends an elicitation request with a message and expected data structure
28+
2. Client presents the request to the user with appropriate UI
29+
3. User accepts, declines, or cancels the request
30+
4. Client validates and returns the response to the server
31+
5. Server continues processing with the provided information
32+
33+
## Request Structure
34+
35+
Elicitation requests include two key components:
36+
37+
### Message
38+
39+
A clear, human-readable explanation of what information is needed and why.
40+
41+
### Schema
42+
43+
A JSON Schema that defines the expected structure of the response. The schema is intentionally limited to flat objects with primitive types to simplify client implementation.
44+
45+
Example request:
46+
47+
```json
48+
{
49+
"message": "Please provide your GitHub username",
50+
"requestedSchema": {
51+
"type": "object",
52+
"properties": {
53+
"username": {
54+
"type": "string",
55+
"title": "GitHub Username",
56+
"description": "Your GitHub username (e.g., octocat)"
57+
}
58+
},
59+
"required": ["username"]
60+
}
61+
}
62+
```
63+
64+
## Supported Data Types
65+
66+
Elicitation supports these primitive types:
67+
68+
### Text Input
69+
70+
```json
71+
{
72+
"type": "string",
73+
"title": "Project Name",
74+
"description": "Name for your new project",
75+
"minLength": 3,
76+
"maxLength": 50
77+
}
78+
```
79+
80+
### Numbers
81+
82+
```json
83+
{
84+
"type": "number",
85+
"title": "Port Number",
86+
"description": "Port to run the server on",
87+
"minimum": 1024,
88+
"maximum": 65535
89+
}
90+
```
91+
92+
### Boolean Choices
93+
94+
```json
95+
{
96+
"type": "boolean",
97+
"title": "Enable Analytics",
98+
"description": "Send anonymous usage statistics",
99+
"default": false
100+
}
101+
```
102+
103+
### Selection Lists
104+
105+
```json
106+
{
107+
"type": "string",
108+
"title": "Environment",
109+
"enum": ["development", "staging", "production"],
110+
"enumNames": ["Development", "Staging", "Production"]
111+
}
112+
```
113+
114+
## User Response Actions
115+
116+
Users can respond to elicitation requests in three ways:
117+
118+
1. **Accept**: User provides the requested information
119+
2. **Decline**: User explicitly refuses to provide information
120+
3. **Cancel**: User dismisses without making a choice (e.g., closes dialog)
121+
122+
Servers should handle each response appropriately:
123+
124+
- Accept → Process the provided data
125+
- Decline → Offer alternatives or adjust workflow
126+
- Cancel → Consider retrying later or using defaults
127+
128+
## Best Practices
129+
130+
When implementing elicitation:
131+
132+
### For Servers
133+
134+
1. **Be Clear**: Write descriptive messages explaining why information is needed
135+
2. **Be Minimal**: Only request essential information
136+
3. **Be Flexible**: Have fallbacks for declined or cancelled requests
137+
4. **Be Timely**: Request information when actually needed, not preemptively
138+
5. **Be Respectful**: Never request sensitive information like passwords or tokens
139+
140+
### For Clients
141+
142+
1. **Be Transparent**: Clearly show which server is requesting information
143+
2. **Be Protective**: Allow users to review and modify responses
144+
3. **Be Validating**: Check responses against the provided schema
145+
4. **Be Empowering**: Make decline and cancel options prominent
146+
5. **Be Limiting**: Implement rate limiting to prevent spam
147+
148+
## Common Use Cases
149+
150+
Elicitation excels in scenarios like:
151+
152+
- **Initial Setup**: Gathering configuration during first-time setup
153+
- **Dynamic Workflows**: Requesting context-specific information
154+
- **User Preferences**: Collecting optional settings and preferences
155+
- **Project Details**: Gathering metadata about resources being created
156+
- **Service Integration**: Requesting usernames or IDs for external services
157+
158+
## Example Workflow
159+
160+
Here's a typical elicitation interaction:
161+
162+
```mermaid
163+
sequenceDiagram
164+
participant User
165+
participant Client
166+
participant Server
167+
168+
Note over Server,Client: Server initiates elicitation
169+
Server->>Client: elicitation/create
170+
171+
Note over Client,User: Human interaction
172+
Client->>User: Present elicitation UI
173+
User-->>Client: Provide requested information
174+
175+
Note over Server,Client: Complete request
176+
Client-->>Server: Return user response
177+
178+
Note over Server: Continue processing with new information
179+
```
180+
181+
182+
## Security Considerations
183+
184+
<Warning>
185+
Servers must never use elicitation to request passwords, API keys, tokens, or
186+
other sensitive credentials. Use proper authentication flows instead.
187+
</Warning>
188+
189+
Key security guidelines:
190+
191+
1. Servers should only request non-sensitive information
192+
2. Clients should clearly indicate which server is requesting data
193+
3. Users should always have the option to decline
194+
4. Responses should be validated against the schema
195+
5. Rate limiting should prevent request flooding
196+
197+
## Implementation Example
198+
199+
Here's how a server might use elicitation to gather project information:
200+
201+
```typescript
202+
// Server requests project details
203+
const response = await client.request("elicitation/create", {
204+
message: "Let's set up your new project",
205+
requestedSchema: {
206+
type: "object",
207+
properties: {
208+
name: {
209+
type: "string",
210+
title: "Project Name",
211+
description: "A descriptive name for your project",
212+
},
213+
framework: {
214+
type: "string",
215+
title: "Framework",
216+
enum: ["react", "vue", "angular", "none"],
217+
enumNames: ["React", "Vue", "Angular", "None"],
218+
},
219+
useTypeScript: {
220+
type: "boolean",
221+
title: "Use TypeScript",
222+
default: true,
223+
},
224+
},
225+
required: ["name", "framework"],
226+
},
227+
});
228+
229+
// Handle the response
230+
if (response.action === "accept") {
231+
// Create project with provided details
232+
await createProject(response.content);
233+
} else if (response.action === "decline") {
234+
// Use defaults or offer alternatives
235+
await createDefaultProject();
236+
} else {
237+
// User cancelled - perhaps retry later
238+
console.log("Project creation cancelled");
239+
}
240+
```
241+
242+
This approach creates a smooth, interactive experience while respecting user control and privacy.

0 commit comments

Comments
 (0)