CPN 한국어 자습서 · 외부 문서 한국어 미러
MCP 문서 · Specification
Elicitation · 원문: modelcontextprotocol.io/specification/2025-11-25/client/elicitation
아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.
MCP(Model Context Protocol)는 서버가 상호작용 중에 클라이언트를 통해 사용자에게 추가 정보를 요청하는 표준화된 방법을 제공합니다. 이 흐름은 클라이언트가 사용자 상호작용과 데이터 공유에 대한 제어권을 유지하면서, 서버가 필요한 정보를 동적으로 수집할 수 있도록 합니다.
정보 요청(Elicitation)은 두 가지 모드를 지원합니다.
MCP의 정보 요청은 다른 MCP 서버 기능 내부에 중첩된 사용자 입력 요청을 가능하게 함으로써 서버가 대화형 워크플로를 구현할 수 있도록 합니다.
구현체는 필요에 맞는 어떠한 인터페이스 패턴을 통해서도 정보 요청을 자유롭게 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.
주의: 신뢰·안전 및 보안을 위해:
- 서버는 비밀번호, API 키, 액세스 토큰, 결제 정보 등 민감한 정보를 요청하기 위해 폼 모드 정보 요청을 사용해서는 안 됩니다(MUST NOT).
- 서버는 이러한 민감한 정보가 포함된 상호작용에는 URL 모드를 사용해야 합니다(MUST).
MCP 클라이언트는 다음을 수행해야 합니다(MUST): * 어떤 서버가 정보를 요청하는지 명확히 알 수 있는 UI 제공 * 사용자 개인 정보를 존중하고 명확한 거절 및 취소 옵션 제공 * 폼 모드의 경우, 전송 전에 사용자가 응답을 검토하고 수정할 수 있도록 허용 * URL 모드의 경우, 대상 도메인/호스트를 명확히 표시하고 목표 URL로 이동하기 전에 사용자 동의 수집
정보 요청을 지원하는 클라이언트는 초기화 중에 elicitation 기능을 선언해야 합니다(MUST).
{
"capabilities": {
"elicitation": {
"form": {},
"url": {}
}
}
}
이전 버전과의 호환성을 위해, 빈 기능 객체는 form 모드만 지원한다고 선언하는 것과 동일합니다.
{
"capabilities": {
"elicitation": {}, // { "form": {} }와 동일
},
}
사용자에게 정보를 요청하기 위해 서버는 elicitation/create 요청을 전송합니다.
모든 정보 요청에는 다음이 포함되어야 합니다(MUST).
| 이름 | 타입 | 옵션 | 설명 |
|---|---|---|---|
mode |
string | form, url |
정보 요청의 모드. 폼 모드의 경우 선택적 (생략 시 "form" 기본값). |
message |
string | 상호작용이 필요한 이유를 설명하는 사람이 읽을 수 있는 메시지. |
폼 모드 정보 요청은 mode: "form"을 지정하거나 mode 필드를 생략해야 하며(MUST), 다음을 포함해야 합니다.
| 이름 | 타입 | 설명 |
|---|---|---|
requestedSchema |
object | 예상 응답의 구조를 정의하는 JSON 스키마(schema). |
스키마(schema)는 다음 기본 타입으로 제한됩니다.
json
{
"type": "string",
"title": "Display Name",
"description": "Description text",
"minLength": 3,
"maxLength": 50,
"pattern": "^[A-Za-z]+$",
"format": "email",
"default": "user@example.com"
}
지원 형식: email, uri, date, date-time
json
{
"type": "number",
"title": "Display Name",
"description": "Description text",
"minimum": 0,
"maximum": 100,
"default": 50
}
json
{
"type": "boolean",
"title": "Display Name",
"description": "Description text",
"default": false
}
json
{
"type": "string",
"title": "Color Selection",
"enum": ["Red", "Green", "Blue"],
"default": "Red"
}
json
{
"type": "array",
"title": "Color Selection",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "string",
"enum": ["Red", "Green", "Blue"]
},
"default": ["Red", "Green"]
}
요청:
{
"jsonrpc": "2.0",
"id": 1,
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Please provide your GitHub username",
"requestedSchema": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
}
}
응답:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"action": "accept",
"content": {
"name": "octocat"
}
}
}
참고: URL 모드 정보 요청은 MCP 명세
2025-11-25버전에서 도입되었습니다. 설계와 구현은 향후 프로토콜 개정에서 변경될 수 있습니다.
URL 모드 정보 요청은 서버가 MCP 클라이언트를 통과해서는 안 되는 대역 외(out-of-band) 상호작용을 위해 사용자를 외부 URL로 안내할 수 있도록 합니다. 이는 인증 흐름, 결제 처리, 기타 민감하거나 안전한 작업에 필수적입니다.
URL 모드 정보 요청은 mode: "url", message를 지정해야 하며(MUST) 다음을 포함해야 합니다.
| 이름 | 타입 | 설명 |
|---|---|---|
url |
string | 사용자가 이동해야 하는 URL. |
elicitationId |
string | 정보 요청의 고유 식별자. |
요청:
{
"jsonrpc": "2.0",
"id": 3,
"method": "elicitation/create",
"params": {
"mode": "url",
"elicitationId": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://mcp.example.com/ui/set_api_key",
"message": "Please provide your API key to continue."
}
}
응답:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"action": "accept"
}
}
action: "accept" 응답은 사용자가 상호작용에 동의했음을 나타냅니다. 상호작용이 완료되었음을 의미하지는 않습니다. 상호작용은 대역 외에서 발생하며 서버가 완료 알림을 전송할 때까지 클라이언트는 결과를 알 수 없습니다.
서버는 URL 모드 정보 요청으로 시작된 대역 외 상호작용이 완료되면 notifications/elicitation/complete 알림을 전송할 수 있습니다(MAY).
{
"jsonrpc": "2.0",
"method": "notifications/elicitation/complete",
"params": {
"elicitationId": "550e8400-e29b-41d4-a716-446655440000"
}
}
정보 요청이 완료되어야 처리할 수 있는 요청의 경우, 서버는 URLElicitationRequiredError (코드 -32042)를 반환할 수 있습니다(MAY).
오류 응답:
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32042,
"message": "This request requires more information.",
"data": {
"elicitations": [
{
"mode": "url",
"elicitationId": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://mcp.example.com/connect?elicitationId=550e8400-e29b-41d4-a716-446655440000",
"message": "Authorization is required to access your Example Co files."
}
]
}
}
}
sequenceDiagram
participant User
participant Client
participant Server
Note over Server: Server initiates elicitation
Server->>Client: elicitation/create (mode: form)
Note over User,Client: Present elicitation UI
User-->>Client: Provide requested information
Note over Server,Client: Complete request
Client->>Server: Return user response
Note over Server: Continue processing with new information
sequenceDiagram
participant UserAgent as User Agent (Browser)
participant User
participant Client
participant Server
Note over Server: Server initiates elicitation
Server->>Client: elicitation/create (mode: url)
Client->>User: Present consent to open URL
User-->>Client: Provide consent
Client->>UserAgent: Open URL
Client->>Server: Accept response
Note over User,UserAgent: User interaction
UserAgent-->>Server: Interaction complete
Server-->>Client: notifications/elicitation/complete (optional)
Note over Server: Continue processing with new information
정보 요청 응답은 세 가지 행동 모델을 사용합니다.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"action": "accept",
"content": {
"propertyName": "value"
}
}
}
세 가지 응답 행동:
action: "accept"): 사용자가 명시적으로 승인하고 데이터와 함께 제출했습니다.
* 폼 모드: content 필드에 요청된 스키마와 일치하는 제출 데이터 포함
* URL 모드: content 필드 생략action: "decline"): 사용자가 명시적으로 요청을 거절했습니다.
* content 필드는 일반적으로 생략됩니다.action: "cancel"): 사용자가 명시적인 선택 없이 닫았습니다.
* content 필드는 일반적으로 생략됩니다.원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.
원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation