샘플링

MCP(Model Context Protocol)는 서버가 클라이언트를 통해 언어 모델에 LLM 샘플링("완성" 또는 "생성")을 요청하는 표준화된 방법을 제공합니다. 이 흐름은 클라이언트가 모델 접근, 선택, 권한에 대한 제어권을 유지하면서 서버가 AI 기능을 활용할 수 있도록 합니다. 서버 API 키가 필요하지 않습니다. 서버는 텍스트, 오디오, 이미지 기반 상호작용을 요청하고 선택적으로 MCP 서버의 컨텍스트를 프롬프트(prompt)에 포함할 수 있습니다.

사용자 상호작용 모델

MCP의 샘플링은 다른 MCP 서버 기능 내부에 중첩된 LLM 호출을 가능하게 함으로써 서버가 에이전트적 동작을 구현할 수 있도록 합니다.

구현체는 필요에 맞는 어떠한 인터페이스 패턴을 통해서도 샘플링을 자유롭게 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.

주의: 신뢰·안전 및 보안을 위해, 샘플링 요청을 거부할 수 있는 사람이 항상 루프에 있어야 합니다(SHOULD).

애플리케이션은 다음을 수행해야 합니다(SHOULD): * 샘플링 요청을 쉽고 직관적으로 검토할 수 있는 UI 제공 * 전송 전에 사용자가 프롬프트(prompt)를 보고 편집할 수 있도록 허용 * 전달 전에 생성된 응답을 검토를 위해 제시

샘플링에서의 도구 사용

서버는 tools 배열과 선택적 toolChoice 구성을 제공하여 샘플링 중에 클라이언트의 LLM이 도구를 사용하도록 요청할 수 있습니다. 클라이언트는 sampling.tools 기능을 통해 도구 사용 지원을 선언해야 합니다(MUST).

기능 선언

샘플링을 지원하는 클라이언트는 초기화 중에 sampling 기능을 선언해야 합니다(MUST).

기본 샘플링:

{
  "capabilities": {
    "sampling": {}
  }
}

도구 사용 지원 포함:

{
  "capabilities": {
    "sampling": {
      "tools": {}
    }
  }
}

참고: includeContext 파라미터 값 "thisServer"와 "allServers"는 소프트 deprecated입니다. 서버는 클라이언트가 sampling.context 기능을 선언하지 않는 한 이 값을 사용하지 않아야 합니다(SHOULD NOT).

프로토콜 메시지

메시지 생성

언어 모델 생성을 요청하기 위해 서버는 sampling/createMessage 요청을 전송합니다.

요청:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

응답:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

도구를 사용한 샘플링

도구 사용 기능과 함께 LLM 생성을 요청하기 위해 서버는 요청에 tools와 선택적 toolChoice를 포함합니다.

요청 (Server → Client):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What's the weather like in Paris and London?"
        }
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "toolChoice": {
      "mode": "auto"
    },
    "maxTokens": 1000
  }
}

응답 (Client → Server):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "call_abc123",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      },
      {
        "type": "tool_use",
        "id": "call_def456",
        "name": "get_weather",
        "input": {
          "city": "London"
        }
      }
    ],
    "model": "claude-3-sonnet-20240307",
    "stopReason": "toolUse"
  }
}

다중 턴 도구 루프

LLM으로부터 도구 사용 요청을 받은 후, 서버는 일반적으로 다음을 수행합니다.

1. 요청된 도구 사용을 실행합니다.
2. 도구 결과를 추가하여 새 샘플링 요청을 전송합니다.
3. LLM의 응답을 수신합니다(새 도구 사용이 포함될 수 있음).
4. 필요한 만큼 반복합니다.

메시지 내용 제약

도구 결과 메시지

사용자 메시지에 도구 결과(타입: "tool_result")가 포함된 경우, 반드시 도구 결과만 포함해야 합니다(MUST). 같은 메시지에 도구 결과를 다른 콘텐츠 타입(텍스트, 이미지, 오디오)과 혼합하는 것은 허용되지 않습니다.

도구 사용과 결과의 균형

샘플링에서 도구 사용 시, ToolUseContent 블록을 포함하는 모든 어시스턴트 메시지 다음에는 반드시 ToolResultContent 블록으로만 구성된 사용자 메시지가 와야 합니다(MUST). 각 도구 사용은 대응하는 도구 결과와 매칭되어야 합니다.

크로스-API 호환성

메시지 역할

MCP는 두 가지 역할을 사용합니다: "user"와 "assistant".

도구 선택 모드

CreateMessageRequest.params.toolChoice는 모델의 도구 사용 능력을 제어합니다.

• {mode: "auto"}: 모델이 도구 사용 여부 결정 (기본값)
• {mode: "required"}: 완료 전에 모델이 반드시 하나 이상의 도구를 사용해야 합니다.
• {mode: "none"}: 모델이 어떤 도구도 사용해서는 안 됩니다.

병렬 도구 사용

MCP는 모델이 병렬로 여러 도구 사용 요청을 할 수 있도록 허용합니다. 모든 주요 제공업체 API(Claude, OpenAI, Gemini)가 이를 지원합니다.

메시지 흐름

sequenceDiagram
    participant Server
    participant Client
    participant User
    participant LLM

    Note over Server,Client: Server initiates sampling
    Server->>Client: sampling/createMessage

    Note over Client,User: Human-in-the-loop review
    Client->>User: Present request for approval
    User-->>Client: Review and approve/modify

    Note over Client,LLM: Model interaction
    Client->>LLM: Forward approved request
    LLM-->>Client: Return generation

    Note over Client,User: Response review
    Client->>User: Present response for approval
    User-->>Client: Review and approve/modify

    Note over Server,Client: Complete request
    Client-->>Server: Return approved response

데이터 타입

모델 선호도

모델 선택은 추상 기능 우선순위와 선택적 모델 힌트(hint)를 결합한 선호도 시스템을 사용합니다.

기능 우선순위 (0-1 정규화)

• costPriority: 비용 최소화가 얼마나 중요합니까? 높을수록 저렴한 모델을 선호합니다.
• speedPriority: 낮은 레이턴시가 얼마나 중요합니까? 높을수록 빠른 모델을 선호합니다.
• intelligencePriority: 고급 기능이 얼마나 중요합니까? 높을수록 더 유능한 모델을 선호합니다.

모델 힌트

{
  "hints": [
    { "name": "claude-3-sonnet" },
    { "name": "claude" }
  ],
  "costPriority": 0.3,
  "speedPriority": 0.8,
  "intelligencePriority": 0.5
}

힌트는 모델 이름과 유연하게 매칭될 수 있는 서브스트링(substring)으로 처리됩니다. 클라이언트는 힌트를 다른 제공업체의 동등한 모델에 매핑할 수 있습니다(MAY). 힌트는 권고 사항이며, 클라이언트가 최종 모델을 선택합니다.

오류 처리

클라이언트는 일반적인 실패 사례에 대해 오류를 반환해야 합니다(SHOULD).

• 사용자가 샘플링 요청을 거절: -1
• 요청에 도구 결과 누락: -32602 (Invalid params)
• 다른 콘텐츠와 도구 결과 혼합: -32602 (Invalid params)

보안 고려사항

1. 클라이언트는 사용자 승인 제어를 구현해야 합니다(SHOULD).
2. 양측은 메시지 내용을 검증해야 합니다(SHOULD).
3. 클라이언트는 속도 제한을 구현해야 합니다(SHOULD).
4. 도구가 사용되는 경우, 서버는 각 ToolUseContent 항목이 매칭되는 toolUseId를 가진 ToolResultContent 항목으로 응답되도록 해야 합니다(MUST).
5. 양측은 도구 루프에 대한 반복 제한을 구현해야 합니다(SHOULD).

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/sampling · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/sampling