ChatGPT 앱 스토어 출시를 통해 배운 MCP 및 도구 설계 교훈

실용적 조언

도구 설명은 300자 이내로 작성하고, 'Returns...'와 같은 3인칭 기능 묘사 방식을 사용하라.
데이터 필드와 개인정보 처리방침 간의 리스트를 만들어 1:1로 매칭되는지 제출 전 전수 조사하라.
데이터 쓰기 기능이 있는 도구는 반드시 destructiveHint를 true로 설정하라.

섹션별 상세

ChatGPT 모델이 한 턴에 여러 도구를 호출하는 것을 기피하는 경향이 확인됐다. 6개의 세분화된 도구를 제공했을 때 모델은 일부 데이터만 가져오는 문제가 발생했으나, 이를 2개의 복합 도구로 통합하자 필요한 데이터를 한 번에 정확히 수집했다. 데이터 타입이 아닌 사용자의 질문 의도를 중심으로 도구를 설계하는 것이 모델의 도구 호출 최소화 전략에 대응하는 핵심이다.

MCP는 기본적으로 상태를 유지(Stateful)하므로 로드 밸런서를 통한 수평 확장 시 세션 미찾음 오류가 발생한다. 인스턴스 A에서 생성된 세션이 인스턴스 B로 라우팅될 때 거부되는 문제를 해결하기 위해, 모든 인스턴스에서 세션 ID를 자동 초기화하는 무상태(Stateless) 모드 도입이 필수적이다. Quarkus 환경에서는 특정 설정을 통해 이를 해결했으며, Nginx 라운드 로빈 환경에서 100% 성공률을 검증했다.

text

quarkus.mcp.server.http.streamable.auto-init=true

Quarkus MCP 서버에서 수평 확장을 위해 무상태(Stateless) 모드를 활성화하는 설정 예시

OpenAI 심사 시 도구 설명에 포함된 강제적 표현(MUST, ALWAYS)은 조작적인 언어로 간주되어 거절 사유가 된다. '반드시 이 도구를 먼저 호출하라'는 식의 지시어 대신, 도구가 반환하는 데이터의 사실적 정보를 300자 이내로 중립적으로 기술해야 한다. 모델의 행동을 규정하려 하지 말고 API 레퍼런스 문서처럼 기능 중심으로 작성하는 것이 권장된다.

사용자 요청과 직접 관련 없는 내부 ID, 타임스탬프, 텔레메트리 데이터는 응답에서 모두 제거해야 한다. OpenAI 리뷰어는 개인 식별자나 불필요한 진단 데이터가 포함된 경우 데이터 최소화 원칙 위반으로 앱을 거절한다. 응답 필드 하나하나가 UI 렌더링이나 사용자 답변에 필수적인지 엄격하게 검토하고 로그에서도 이를 제거하는 과정이 필요하다.

개인정보 처리방침(Privacy Policy)과 실제 도구가 반환하는 데이터 필드 간의 불일치는 즉각적인 거절 사유이다. 리뷰어는 도구가 반환하는 모든 필드와 정책 문서의 선언 내용을 대조하며, 파생 데이터나 계산된 결과값도 공시 대상에 포함되어야 한다. 특히 OpenAI를 데이터 수신자로 명시하고 인증 제공자 목록을 정확히 기재하는 것이 심사 통과에 결정적이다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — Anthropic에서 제안한 개방형 표준으로, AI 모델이 데이터 소스 및 도구와 안전하고 일관되게 연결될 수 있도록 하는 프로토콜이다. 로컬 데이터나 타사 서비스의 컨텍스트를 LLM에 효율적으로 주입하는 데 필수적이다.
무상태 모드(Stateless Mode): — 서버가 클라이언트의 이전 요청 상태를 저장하지 않는 방식이다. MCP 서버를 수평적으로 확장할 때 세션 정보가 특정 인스턴스에 종속되지 않도록 하여 로드 밸런싱 환경에서 오류를 방지하는 데 중요하다.
도구 어노테이션(Tool Annotation): — LLM이 특정 도구의 기능, 위험성(destructiveHint), 읽기 전용 여부 등을 이해할 수 있도록 메타데이터를 추가하는 기법이다. OpenAI 앱 스토어 심사 시 모델의 오작동을 방지하기 위한 핵심 검토 대상이다.
스티키 세션(Sticky Session): — 로드 밸런서가 특정 사용자의 모든 요청을 처음 연결된 서버 인스턴스로만 보내는 기술이다. MCP의 세션 유지 문제를 해결할 수 있지만, 서버 부하 분산의 효율성을 떨어뜨리는 단점이 있다.

코드 예제

java

@ToolMemoryId
// LangChain4J를 사용하여 모델에 노출하지 않고 사용자 ID를 스레딩하는 방식

LangChain4J를 사용하여 인증된 사용자 ID를 안전하게 처리하는 예시

언급된 도구

quarkus-mcp-server추천

Java Quarkus 기반의 MCP 서버 구현 라이브러리

LangChain4J추천

Java 환경에서 LLM 및 도구 연동을 위한 프레임워크

Testcontainers추천

통합 테스트 시 독립적인 컨테이너 환경 제공

언급된 리소스

GitHubquarkus-mcp-server GitHub Issue #518