[MCP] MCP 도구(Tools)

by


본 포스트에서는 MCP(Model Context Protocol)의 핵심 구성요소 중 하나인 도구(Tools)에 대해 더욱 깊이 있게 살펴보겠습니다.

도구란 무엇인가?

MCP의 도구(Tools)는 서버가 클라이언트에 실행 가능한 기능을 노출할 수 있도록 하는 요소로, AI 모델이 외부 시스템과 상호작용하고, 계산을 수행하거나, 실제 작업을 수행할 수 있게 합니다. 도구는 서버에서 클라이언트로 노출되며, AI 모델이 자동으로 도구를 호출할 수 있습니다.

도구의 주요 특징

  • 발견 가능성: 클라이언트는 서버의 tools/list 엔드포인트를 통해 사용 가능한 도구 목록을 얻을 수 있습니다.
  • 호출 가능성: 도구는 tools/call 엔드포인트를 통해 호출되며, 서버가 요청된 작업을 수행하고 결과를 반환합니다.
  • 유연성: 도구는 간단한 연산에서부터 복잡한 API 상호작용까지 다양한 작업을 처리할 수 있습니다.

도구 정의 구조

도구는 일반적으로 다음과 같은 JSON 구조로 정의됩니다:

{
  "name": "string",
  "description": "optional",
  "inputSchema": {
    "type": "object",
    "properties": { ... }
  }
}

도구 구현 예시

다음은 MCP 서버에서 기본 도구를 구현하는 예입니다:

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "calculate_sum",
    description: "Add two numbers together",
    inputSchema: {
      type: "object",
      properties: {
        a: { type: "number" },
        b: { type: "number" }
      },
      required: ["a", "b"]
    }
  }]
}));

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [{ type: "text", text: String(a + b) }]
    };
  }
  throw new Error("Tool not found");
});

예시 도구 패턴

시스템 운영

로컬 시스템과 상호작용하는 도구:

{
  "name": "execute_command",
  "description": "Run a shell command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": { "type": "string" },
      "args": { "type": "array", "items": { "type": "string" } }
    }
  }
}

API 통합

외부 API를 래핑하는 도구:

{
  "name": "github_create_issue",
  "description": "Create a GitHub issue",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" },
      "labels": { "type": "array", "items": { "type": "string" } }
    }
  }
}

데이터 처리

데이터 분석 및 처리 도구:

{
  "name": "analyze_csv",
  "description": "Analyze a CSV file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filepath": { "type": "string" },
      "operations": {
        "type": "array",
        "items": { "enum": ["sum", "average", "count"] }
      }
    }
  }
}

도구 작성 모범 사례

  • 명확하고 설명적인 이름과 설명 제공
  • 상세한 JSON 스키마로 매개변수 정의
  • 도구 설명에 사용 예시 포함
  • 적절한 오류 처리와 입력 검증 구현
  • 집중적이고 원자적인 작업 수행
  • 예상 반환 값 구조 명시
  • 리소스 집약적 작업에 대한 속도 제한 설정

보안 고려 사항

  • 모든 입력 매개변수와 명령 검증
  • 파일 경로 및 시스템 명령어 정리
  • 인증 및 접근 제어 구현
  • 명령 주입 공격 방지
  • 민감한 데이터 처리 시 주의
  • 보안 관련 오류의 적절한 로깅

오류 처리

도구 실행 중 발생한 오류는 결과 객체 내에서 보고되어야 합니다:

try {
  const result = performOperation();
  return { content: [{ type: "text", text: `Operation successful: ${result}` }] };
} catch (error) {
  return { isError: true, content: [{ type: "text", text: `Error: ${error.message}` }] };
}

이 방식을 통해 AI 모델은 오류 발생 여부를 명확히 파악하고 대응할 수 있습니다.

결론

도구는 MCP에서 AI 모델이 다양한 외부 작업을 효율적이고 안전하게 수행하도록 돕는 중요한 구성요소입니다. 잘 설계된 도구는 AI 시스템의 확장성과 효율성을 크게 향상시킬 수 있습니다. 다음 포스트에서는 MCP의 샘플링(Sampling)에 대해 알아보겠습니다.

참고 자료

  • https://modelcontextprotocol.io/introduction


Leave a Comment