플러그인의 MCP 서버는 도구를 통해 ChatGPT와 Codex에 작업과 데이터를 제공합니다. 사용 사례를 구상한 다음, 서버를 구현하기 전에 도구를 정의하세요.
각 도구는 사용자가 목표를 달성하는 데 도움이 되어야 합니다. 내부 API를 그대로 도구로 옮기기 전에 사용자가 해당 기능을 어떻게 요청하고 사용할지 고려하세요.
사용 사례별 도구 설계하기
지원하는 각 사용 사례에 대해 다음 단계를 따르세요.
- 사용자가 기대하는 결과를 적으세요.
- 그 결과를 얻는 데 필요한 정보를 나열하세요.
- 서버가 수행해야 할 읽기, 쓰기 또는 외부 작업을 파악하세요.
- 사용자 관점에서 하나의 작업을 이루는 연산은 한 도구로 묶으세요.
- 필요한 권한, 안전상 위험 또는 확인 요건이 다른 연산은 별도 도구로 나누세요.
예를 들어 프로젝트 플러그인은 다음 도구를 제공할 수 있습니다.
list_projects로 프로젝트를 찾습니다.get_project로 프로젝트 하나의 정보를 확인합니다.create_project로 프로젝트를 만듭니다.update_project로 프로젝트의 세부 정보를 변경합니다.archive_project로 프로젝트를 보관 처리합니다. 이는 프로젝트 상태에 중요한 변화를 일으키는 작업입니다.
모델과 사용자가 정보 조회와 상태를 변경하는 작업을 구분할 수 있도록 읽기와 쓰기를 분리하세요.
각 도구의 계약 정의하기
설계 중인 각 도구에 대해 다음 항목을 기록하세요.
| 항목 | 정의할 내용 |
|---|---|
| 이름 | 도구의 동작을 나타내며 일관되게 유지할 식별자 |
| 제목 | 사람이 쉽게 이해할 수 있도록 동작을 간결하게 표현한 문구 |
| 설명 | 도구로 달성하려는 사용자 목표와 도구를 호출해야 하는 조건 |
| 입력 스키마 | 필수 및 선택 매개변수, 타입, 허용 값, 제한 사항 |
| 출력 스키마 | 모델이 확인하고 재사용할 수 있는 구조화된 필드 |
| 권한 부여 | 서버가 확인해야 하는 계정, 역할 또는 리소스 접근 권한 |
| 사이드 이펙트 | 도구가 변경할 수 있는 데이터 또는 외부 상태 |
| 실패 시 동작 | 모델이 설명하거나 복구할 수 있는 오류 |
입력값을 명시하세요. 올바른 실행에 필요한 식별자, 계정 범위 등의 값을 모델이 추측하도록 두지 마세요.
후속 호출에 사용할 수 있도록 일관된 식별자를 반환하고, 필요한 정보를 충분히 담아 구조화된 형태로 제공하세요. 결과에 비밀 정보, 액세스 토큰, 내부 진단 정보 또는 불필요한 개인 데이터를 포함하지 마세요.
모델이 도구를 선택할 수 있도록 설명 작성하기
모델은 도구 설명을 바탕으로 어떤 도구가 요청에 적합한지 판단합니다. 도구 설명에는 해당 도구를 쓰려는 사용자의 의도를 담고 구현 방식은 생략하세요.
좋은 설명은 다음 요건을 충족합니다.
- 도구가 어떤 작업을 수행하는지 명시합니다.
- 언제 사용해야 하는지 설명합니다.
- 비슷한 도구와 어떤 점이 다른지 밝힙니다.
- 중요한 제한 사항이나 사전 요건을 명시합니다.
도구 이름만 되풀이하거나 사용자가 모르는 내부 서비스 용어를 쓰는 설명은 피하세요.
안전 관련 어노테이션 설계하기
도구의 실제 동작에 따라 어노테이션을 지정하세요. 다음 힌트의 공식 정의와 기본값, 힌트 간 상호작용은 MCP의 ToolAnnotations 스키마를 참고하세요.
readOnlyHint는 도구가 상태를 변경할 수 없는 경우에만true입니다.destructiveHint는 도구가 되돌릴 수 없거나 되돌리기 어려운 결과를 초래할 수 있으면true입니다.openWorldHint는 도구가 공개 인터넷에 접근하거나 접근 대상이 미리 한정되지 않은 외부 리소스를 이용하면true입니다. 웹 검색과 같은 읽기 전용 작업도 여기에 포함됩니다. 접근 범위가 한정된 비공개 계정이나 워크스페이스는 외부에서 호스팅된다는 이유만으로 이 조건에 해당하지 않습니다.
어노테이션은 서버 측 권한 검사, 입력값 검증 또는 중요한 영향을 미치는 작업에 대한 확인 절차를 대신할 수 없습니다.
지원 범위와 한계 점검하기
설계한 도구를 전체 사용 사례 목록과 비교하세요.
- 지원하는 모든 사용 사례에서 도구를 사용해 유용한 결과를 얻을 수 있는지 확인하세요.
- 문서화된 사용 사례 어디에도 쓰이지 않는 도구를 찾으세요.
- 사용자가 쓰기 작업 전에 정보를 조회하는 데 필요한 도구가 빠졌는지 확인하세요.
- 지원하지 않는 요청을 받았을 때 무리하게 비슷한 작업을 수행해 위험을 초래하는 대신, 사용자가 이해할 수 있도록 한계를 설명하는지 확인하세요.
- 비슷한 두 도구의 설명이 겹쳐 모델이 어느 도구를 선택해야 할지 혼동할 수 있는지 테스트하세요.
완성한 도구 설계안을 구현과 평가를 위한 체크리스트로 활용하세요. 그런 다음 MCP 서버를 구축하고 대표적인 입력, 유효하지 않은 입력, 요청자에게 필요한 권한이 없는 경우의 입력으로 각 도구의 계약을 테스트하세요.