문제 진단 방법
컴포넌트가 렌더링되지 않거나, 프롬프트에 맞는 도구를 찾지 못하거나, 인증 과정이 반복된다면 먼저 서버, 컴포넌트, ChatGPT 클라이언트 중 어디에서 문제가 발생하는지 확인하세요. 아래 체크리스트에서 자주 발생하는 문제와 해결 방법을 확인할 수 있습니다.
서버, 도구, 도구 탐색 관련 점검 항목은 ChatGPT와 Codex의 플러그인에 모두 적용됩니다. 이 페이지에서 다루는 UI, 위젯 상태, 클라이언트 인증 관련 점검 항목은 ChatGPT의 동작을 기준으로 합니다.
서버 측 문제
- 목록에 도구가 표시되지 않음: 서버가 실행 중이고
/mcp엔드포인트에 연결했는지 확인하세요. 포트를 변경했다면 MCP 서버 URL을 업데이트하고 MCP Inspector를 다시 시작하세요. - 구조화된 콘텐츠만 표시되고 컴포넌트가 보이지 않음: 도구 설명자의
_meta.ui.resourceUri가mimeType: "text/html;profile=mcp-app"으로 등록된 HTML 리소스를 가리키는지 확인하세요. ChatGPT에서는 호환성을 위해_meta["openai/outputTemplate"]을 별칭으로 사용할 수도 있습니다. 해당 리소스가 CSP 오류 없이 로드되는지도 확인하세요. - 스키마 불일치 오류: Python 또는 TypeScript 모델이
outputSchema에 명시된 스키마와 일치하는지 확인하세요. 변경한 후에는 타입을 다시 생성하세요. - 느린 응답: 도구 호출 시간이 수백 밀리초를 넘으면 컴포넌트의 반응이 느리게 느껴집니다. 서버 호출을 프로파일링하고 가능하면 결과를 캐시하세요.
위젯 문제
- 위젯이 로드되지 않음: 브라우저 콘솔이나 MCP Inspector 로그에서 CSP 위반이나 누락된 번들이 있는지 확인하세요. HTML에 컴파일된 JavaScript가 포함되어 있고 번들에 모든 종속성이 포함되어 있는지도 확인하세요.
- 드래그 앤 드롭이나 편집 결과가 유지되지 않음: ChatGPT의 위젯 상태 저장 기능을 사용한다면 상태가 바뀔 때마다
window.openai.setWidgetState를 호출하고, 위젯이 마운트될 때window.openai.widgetState에서 상태를 복원하세요. - 모바일 레이아웃 문제: ChatGPT에서 제공하는 레이아웃 정보를 사용한다면
window.openai.displayMode와window.openai.maxHeight값을 확인해 레이아웃을 조정하세요. 레이아웃 높이를 고정하지 마세요. 마우스 포인터를 올려야만 수행할 수 있는 동작도 피하세요.
도구 탐색 및 진입점 문제
- 도구가 전혀 호출되지 않음: 메타데이터를 다시 검토하세요. “…할 때 이 도구를 사용하세요”처럼 사용 시점이 드러나도록 설명을 고치고, 시작 프롬프트를 업데이트한 뒤 기준 프롬프트 세트로 다시 테스트하세요.
- 잘못된 도구가 선택됨: 비슷한 도구를 구분할 수 있도록 설명을 보완하거나 도구를 사용하면 안 되는 상황을 설명에 명시하세요. 기능이 많은 도구는 용도별로 더 작은 도구로 나누는 것도 고려하세요.
- 런처의 표시 순서가 예상과 다름: 디렉터리 메타데이터를 갱신하고 플러그인 아이콘과 설명이 사용자의 기대에 부합하는지 확인하세요.
인증 문제
- 401 오류: ChatGPT가 OAuth 플로우를 다시 시작해야 한다는 것을 알 수 있도록 오류 응답에
WWW-Authenticate헤더를 포함하세요. 발급자 URL과 대상(audience) 클레임도 다시 확인하세요. - 클라이언트 등록 실패: CIMD를 사용한다면 인가 서버의 메타데이터에
client_id_metadata_document_supported: true가 포함되어 있고 서버가 ChatGPT의 클라이언트 메타데이터 문서를 가져올 수 있는지 확인하세요.private_key_jwt를 사용한다면 인가 서버가 ChatGPT의 공개 JWKS를 가져오고 서명된 클라이언트 어설션을 검증할 수 있는지 확인하세요. DCR을 사용한다면 인가 서버가registration_endpoint를 제공하고 새로 생성된 클라이언트마다 로그인 연결이 하나 이상 활성화되어 있는지 확인하세요. - 기존 MCP 서버 연결에서
invalid_client오류가 반환됨: 동적으로 등록한 OAuth 클라이언트가 여전히 존재하는지 확인하세요. 클라이언트 시크릿이 있다면 인가 서버가 해당 시크릿을 받아들이는지도 확인하세요. ChatGPT는 이 자격 증명을 재사용하므로 새 클라이언트를 만드는 대신 기존 자격 증명을 복원하세요. 액세스 토큰이 만료된 경우에는 해결 방법이 다릅니다.
배포 문제
- ngrok 터널 시간 초과: 터널을 다시 시작하고 URL을 공유하기 전에 로컬 서버가 실행 중인지 확인하세요. 프로덕션에서는 상태 점검 기능을 제공하는 안정적인 호스팅 서비스를 사용하세요.
- 프록시를 거치면 스트리밍이 끊김: 로드 밸런서나 CDN이 서버 전송 이벤트 또는 스트리밍 HTTP 응답을 버퍼링 없이 전달하는지 확인하세요.
지원을 요청할 때
위 항목을 모두 점검한 후에도 문제가 지속되면 다음 절차에 따라 지원을 요청하세요.
- 서버 로그, 컴포넌트 콘솔 로그, ChatGPT 도구 호출 기록과 스크린샷을 수집하세요.
- 입력한 프롬프트와 표시된 확인 메시지를 기록하세요.
- OpenAI 파트너 담당자가 내부에서 문제를 재현할 수 있도록 수집한 정보를 담당자에게 공유하세요.
문제와 점검 결과를 명확하게 기록하면 해결 시간을 줄이고 사용자에게 안정적인 MCP 서버를 제공할 수 있습니다.