byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Specification

도구

Tools · 원문: modelcontextprotocol.io/specification/2025-11-25/server/tools

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

MCP(Model Context Protocol)는 서버가 언어 모델에 의해 호출될 수 있는 도구(tool)를 노출할 수 있도록 합니다. 도구를 통해 모델은 데이터베이스 쿼리, API 호출, 연산 수행 등 외부 시스템과 상호작용할 수 있습니다. 각 도구는 이름으로 고유하게 식별되며, 스키마를 설명하는 메타데이터를 포함합니다.

사용자 상호작용 모델

MCP의 도구는 모델 제어(model-controlled) 방식으로 설계되어 있습니다. 즉, 언어 모델이 컨텍스트 이해와 사용자 프롬프트에 따라 도구를 자동으로 발견하고 호출할 수 있습니다.

단, 구현체는 필요에 맞는 어떤 인터페이스 패턴으로든 도구를 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.

주의: 신뢰와 안전 및 보안을 위해, 도구 호출을 거부할 수 있는 사람이 항상 루프 안에 있어야 합니다(SHOULD).

애플리케이션은 다음을 SHOULD 수행해야 합니다.

  • AI 모델에 노출되는 도구를 명확히 표시하는 UI 제공
  • 도구가 호출될 때 명확한 시각적 표시 삽입
  • 사람이 루프 안에 있도록 작업에 대한 확인 프롬프트 제시

기능(Capabilities)

도구를 지원하는 서버는 tools 기능을 반드시 선언해야 합니다(MUST).

코드 · 명령
{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

listChanged는 사용 가능한 도구 목록이 변경될 때 서버가 알림을 보낼지 여부를 나타냅니다.

프로토콜 메시지

도구 목록 조회

사용 가능한 도구를 발견하기 위해 클라이언트는 tools/list 요청을 보냅니다. 이 작업은 페이지네이션을 지원합니다.

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        },
        "icons": [
          {
            "src": "https://example.com/weather-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ],
        "execution": {
          "taskSupport": "optional"
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

도구 호출

도구를 실행하기 위해 클라이언트는 tools/call 요청을 보냅니다.

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}

목록 변경 알림

사용 가능한 도구 목록이 변경되면, listChanged 기능을 선언한 서버는 다음 알림을 보내야 합니다(SHOULD).

코드 · 명령
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

메시지 흐름

코드 · 명령
sequenceDiagram
    participant LLM
    participant Client
    participant Server

    Note over Client,Server: Discovery
    Client->>Server: tools/list
    Server-->>Client: List of tools

    Note over Client,LLM: Tool Selection
    LLM->>Client: Select tool to use

    Note over Client,Server: Invocation
    Client->>Server: tools/call
    Server-->>Client: Tool result
    Client->>LLM: Process result

    Note over Client,Server: Updates
    Server--)Client: tools/list_changed
    Client->>Server: tools/list
    Server-->>Client: Updated tools

데이터 타입

Tool

도구 정의에는 다음 항목이 포함됩니다.

주의: 신뢰와 안전 및 보안을 위해, 클라이언트는 신뢰할 수 있는 서버에서 제공된 것이 아닌 한 도구 어노테이션(annotation)을 신뢰할 수 없는 것으로 간주해야 합니다(MUST).

도구 이름

도구 결과(Tool Result)

도구 결과에는 구조화된(structured) 콘텐츠 또는 비구조화된(unstructured) 콘텐츠가 포함될 수 있습니다.

비구조화된 콘텐츠는 결과의 content 필드에 반환되며, 서로 다른 타입의 여러 콘텐츠 항목을 포함할 수 있습니다.

참고: 모든 콘텐츠 타입(텍스트, 이미지, 오디오, 리소스 링크, 임베디드 리소스)은 대상, 우선순위, 수정 시간에 대한 메타데이터를 제공하는 선택적 어노테이션을 지원합니다. 이는 리소스와 프롬프트에서 사용하는 것과 동일한 어노테이션 형식입니다.

텍스트 콘텐츠

코드 · 명령
{
  "type": "text",
  "text": "Tool result text"
}

이미지 콘텐츠

코드 · 명령
{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png",
  "annotations": {
    "audience": ["user"],
    "priority": 0.9
  }
}

오디오 콘텐츠

코드 · 명령
{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

리소스 링크

도구는 리소스에 대한 링크를 반환할 수 있습니다(MAY). 이 경우 클라이언트가 구독하거나 가져올 수 있는 URI를 반환합니다.

코드 · 명령
{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

리소스 링크는 클라이언트가 링크를 사용하는 방법을 이해할 수 있도록 일반 리소스와 동일한 리소스 어노테이션을 지원합니다.

참고: 도구가 반환하는 리소스 링크는 resources/list 요청 결과에 반드시 나타나지는 않습니다.

임베디드 리소스

리소스는 적절한 URI 스킴을 사용하여 임베디드 형태로 포함될 수 있습니다(MAY). 임베디드 리소스를 사용하는 서버는 resources 기능을 구현해야 합니다(SHOULD).

코드 · 명령
{
  "type": "resource",
  "resource": {
    "uri": "file:///project/src/main.rs",
    "mimeType": "text/x-rust",
    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
    "annotations": {
      "audience": ["user", "assistant"],
      "priority": 0.7,
      "lastModified": "2025-05-03T14:30:00Z"
    }
  }
}

임베디드 리소스는 클라이언트가 사용 방법을 이해할 수 있도록 일반 리소스와 동일한 리소스 어노테이션을 지원합니다.

구조화된 콘텐츠(Structured Content)

구조화된 콘텐츠는 결과의 structuredContent 필드에 JSON 객체로 반환됩니다.

하위 호환성을 위해 구조화된 콘텐츠를 반환하는 도구는 TextContent 블록에 직렬화된 JSON도 함께 반환해야 합니다(SHOULD).

출력 스키마(Output Schema)

도구는 구조화된 결과를 검증하기 위한 출력 스키마를 제공할 수도 있습니다. 출력 스키마가 제공된 경우:

출력 스키마가 있는 도구 예시:

코드 · 명령
{
  "name": "get_weather_data",
  "title": "Weather Data Retriever",
  "description": "Get current weather data for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Temperature in celsius"
      },
      "conditions": {
        "type": "string",
        "description": "Weather conditions description"
      },
      "humidity": {
        "type": "number",
        "description": "Humidity percentage"
      }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

이 도구에 대한 유효한 응답 예시:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
      }
    ],
    "structuredContent": {
      "temperature": 22.5,
      "conditions": "Partly cloudy",
      "humidity": 65
    }
  }
}

출력 스키마를 제공하면 클라이언트와 LLM이 구조화된 도구 출력을 이해하고 올바르게 처리하는 데 도움이 됩니다.

스키마 예시

기본 2020-12 스키마를 사용하는 도구:

코드 · 명령
{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

명시적 draft-07 스키마를 사용하는 도구:

코드 · 명령
{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

파라미터가 없는 도구:

코드 · 명령
{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

오류 처리

도구는 두 가지 오류 보고 메커니즘을 사용합니다.

  1. 프로토콜 오류(Protocol Errors): 다음과 같은 문제에 대한 표준 JSON-RPC 오류: * 알 수 없는 도구 * 형식이 잘못된 요청(CallToolRequest 스키마를 충족하지 못하는 요청) * 서버 오류

  2. 도구 실행 오류(Tool Execution Errors): isError: true로 도구 결과에 보고되는 오류: * API 실패 * 입력 검증 오류(예: 잘못된 날짜 형식, 범위를 벗어난 값) * 비즈니스 로직 오류

도구 실행 오류에는 언어 모델이 스스로 수정하고 조정된 파라미터로 재시도할 수 있는 실행 가능한 피드백이 포함됩니다. 프로토콜 오류는 요청 구조 자체의 문제를 나타내며, 모델이 수정하기 어렵습니다. 클라이언트는 자기 수정을 가능하게 하기 위해 도구 실행 오류를 언어 모델에 제공해야 합니다(SHOULD). 클라이언트는 프로토콜 오류를 언어 모델에 제공할 수 있지만(MAY), 성공적인 복구 가능성은 낮습니다.

프로토콜 오류 예시:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

도구 실행 오류 예시(입력 검증):

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
      }
    ],
    "isError": true
  }
}

보안 고려 사항

  1. 서버는 다음을 반드시 수행해야 합니다(MUST). * 모든 도구 입력 검증 * 적절한 접근 제어 구현 * 도구 호출 속도 제한 * 도구 출력 새니타이즈(sanitize)

  2. 클라이언트는 다음을 수행해야 합니다(SHOULD). * 민감한 작업에 대해 사용자 확인 요청 * 악의적이거나 우발적인 데이터 유출을 방지하기 위해 서버 호출 전에 도구 입력을 사용자에게 표시 * LLM에 전달하기 전에 도구 결과 검증 * 도구 호출에 타임아웃 구현 * 감사 목적으로 도구 사용 로그 기록

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

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