새벽 2시, 개발자는 네 번째 커피를 마시며 “Something went wrong”라는 에러 메시지만 바라보고 있습니다. MCP 서버는 작동하고, OAuth 엔드포인트는 200을 반환하는데 ChatGPT는 연결을 거부합니다. 공식 문서는 한 가지를 말하지만, 실제 동작은 완전히 다릅니다.
ChatGPT Apps SDK로 개발을 시작하면 마주하게 될 현실입니다. 8억 사용자에게 접근할 수 있다는 기회는 분명 매력적이지만, 그 길은 문서화되지 않은 함정들과 불친절한 에러 메시지로 가득합니다.
개발자 Mark가 몇 주간의 실전 개발 경험을 바탕으로 작성한 이 가이드는 공식 문서가 말해주지 않는 진짜 개발 현실을 담고 있습니다. ChatGPT 내부에서 작동하는 인터랙티브 앱을 만드는 방법부터, 반드시 마주치게 될 CORS 에러와 OAuth 혼란까지 모두 다룹니다.
출처: Everything you need to know about building ChatGPT apps – Humai.blog
ChatGPT 앱이란 무엇인가
ChatGPT 앱은 전통적인 웹앱이나 모바일 앱과 다릅니다. ChatGPT 내부에서 작동하며 AI가 할 수 있는 일을 확장하는 소프트웨어입니다. 사용자가 “Spotify, 금요일 파티용 플레이리스트 만들어줘”라고 말하면 채팅창 안에 완전히 작동하는 Spotify 인터페이스가 나타납니다. 탭 전환도, 복사-붙여넣기도 필요 없습니다.
기술적으로는 세 가지 핵심 요소로 구성됩니다. MCP(Model Context Protocol) 서버는 ChatGPT에게 앱이 무엇을 할 수 있는지 알려주고 실제 기능을 제공합니다. OAuth 2.1 인증은 사용자 식별과 데이터 접근을 처리하죠. 위젯은 채팅 안에 렌더링되는 인터랙티브 UI 컴포넌트입니다.
이 세 요소가 함께 작동하면 ChatGPT 네이티브처럼 느껴지는 경험이 만들어집니다. 모델이 사용자 프롬프트에 따라 도구를 호출하고, 서버가 로직을 실행해 데이터를 반환하며, 위젯이 사용자 친화적으로 표시합니다. 이 모든 것이 제대로 작동하면 정말 마법 같습니다. 문제는 “제대로 작동하게 만드는 것”입니다.
개발자가 꼭 알아야 할 세 가지 함정
첫째, ChatGPT로 바로 테스트하지 마세요. ChatGPT의 에러 메시지는 정보가 전혀 없습니다. OAuth 문제인지, 도구 정의 문제인지, CORS 헤더 문제인지 알려주지 않습니다. 그냥 “Something went wrong”만 표시하죠.
대신 MCP Inspector로 먼저 테스트하세요. 실제 에러 메시지를 보여주고, 요청과 응답을 정확히 볼 수 있으며, 프로토콜 스펙에 맞는지 검증해줍니다. 여기서 모든 것이 작동하는 것을 확인한 후에 ChatGPT로 넘어가야 합니다. 이것만으로도 몇 시간을 아낄 수 있습니다.
둘째, OAuth 역할을 헷갈리지 마세요. 대부분의 개발자는 “Sign in with Google” 같은 OAuth 클라이언트 구현에 익숙합니다. 사용자를 구글로 보내고, 인증하고, 토큰을 받아 구글 API를 호출하는 방식이죠.
ChatGPT 앱에서는 정반대입니다. 당신이 제공자입니다. ChatGPT가 클라이언트고, 당신의 백엔드에 인증해야 합니다. /authorize, /token 엔드포인트를 구현하고, OIDC discovery를 제공하며, PKCE를 지원해야 합니다. 이 역할 전환이 혼란의 주요 원인입니다.
직접 구현하지 말고 Auth0, Clerk, Stytch 같은 기존 인증 제공자를 사용하는 것을 강력히 추천합니다. 보안, 컴플라이언스, 토큰 관리 같은 어려운 부분을 대신 처리해주니까요.
셋째, CORS는 피할 수 없습니다. ChatGPT 앱은 근본적으로 cross-origin입니다. MCP 서버는 당신의 도메인에 있고, OAuth 요청은 OpenAI 인프라에서 오며, 위젯은 oaiusercontent.com에서 실행됩니다. 아무것도 같은 오리진을 공유하지 않습니다.
세 가지 CORS 설정이 필요합니다. MCP 라우트는 ChatGPT 백엔드와 개발 중인 MCP Inspector의 요청을 받아야 하고, OAuth 라우트도 마찬가지입니다. OAuth 토큰으로 이미 보호되므로 Access-Control-Allow-Origin: *를 써도 됩니다. 위젯 에셋은 web-sandbox.oaiusercontent.com과 개발 중인 자신의 도메인에서 접근할 수 있어야 합니다.
위젯 개발의 현실
위젯은 ChatGPT Apps SDK에서 가장 흥미로운 부분입니다. 채팅 안에서 직접 인터랙티브 UI를 렌더링할 수 있다는 것은 정말 혁신적이죠. Figma 앱에 SaaS 아키텍처 다이어그램을 요청하면 ChatGPT 안에 인터랙티브 Figma 캔버스가 나타납니다. 확대, 축소, 요소 선택, 편집까지 가능합니다.
하지만 개발 현실은 까다롭습니다. 위젯은 샌드박스 iframe이고, ChatGPT는 정적 HTML을 기대합니다. 앱이 설치될 때 캐싱되므로 사용자별 동적 렌더링이 불가능합니다. 서버 사이드 렌더링은 완전히 배제되고, 클라이언트 사이드 싱글 페이지 앱을 만들어야 합니다.
ChatGPT는 TypeScript, Tailwind, JSX 같은 현대적 개발 편의 기능을 내장 지원하지 않습니다. 순수 HTML만 받아들입니다. React 앱을 번들링하고, TypeScript를 컴파일하고, CSS를 처리해서 샌드박스 iframe 안에서 cross-origin으로 작동하게 만들어야 합니다.
Vite가 이 과정을 훨씬 쉽게 만들어줍니다. 핫 모듈 리로딩(HMR)으로 변경사항이 거의 즉시 반영되고, TypeScript 컴파일이 자동으로 처리되며, Tailwind 클래스도 그냥 작동합니다. vite-plugin-chatgpt-widgets라는 전용 플러그인까지 있어 보일러플레이트를 많이 줄여줍니다.
디버깅 전략
ChatGPT 앱 디버깅은 인내심과 삼각측량의 예술입니다. 여러 시스템(백엔드, ChatGPT 인프라, 위젯 iframe), 여러 프로토콜(MCP, OAuth, CORS), 그리고 도움이 안 되는 에러 메시지들이 얽혀 있습니다.
효과적인 디버깅 워크플로우는 이렇습니다. MCP Inspector로 시작해서 MCP 서버가 올바르게 응답하는지 확인하세요. 도구를 나열하나요? 도구 호출이 예상 데이터를 반환하나요? 리소스(위젯 HTML)가 제대로 등록되었나요?
상세한 로깅을 사용하세요. MCP 서버로 들어오는 모든 요청을 로깅하고, OAuth 플로우의 각 단계를 로깅하며, 위젯이 에셋을 요청할 때도 로깅하세요. 뭔가 망가졌을 때 파이프라인의 어디서 실패했는지 정확히 알아야 합니다.
OAuth는 별도로 테스트하세요. Postman이나 OAuth 2.0 debugger 같은 도구로 전체 authorization code 플로우를 완료할 수 있는지 확인하세요. 독립적으로는 작동하는데 ChatGPT를 통하면 실패한다면, 문제 범위를 상당히 좁힐 수 있습니다.
브라우저 콘솔을 주시하세요. 위젯이 ChatGPT에 로드될 때도 개발자 도구에 접근할 수 있습니다. CORS 문제, JavaScript 예외, 실패한 에셋 로드가 모두 여기 나타납니다.
플랫폼의 의미와 미래
ChatGPT Apps SDK는 아직 젊습니다. 2025년 말에 출시되었고 핵심 기능은 탄탄하지만, 생태계는 빠르게 진화하고 있습니다. 문서가 업데이트되고, 베스트 프랙티스가 정립되며, 새로운 기능이 추가되는 중입니다.
앱 디렉토리 제출이 열렸다는 것은 이제 앱을 ChatGPT 사용자가 발견할 수 있다는 뜻입니다. 8억 명이 사용하는 플랫폼에서 적절한 순간에 앱이 제안되는 것은 강력한 배포 기회입니다. 하지만 경쟁도 올 것이고, 품질 기준도 높아질 것입니다.
수익화 옵션도 등장하고 있습니다. OpenAI가 Agentic Commerce Protocol 지원을 언급했는데, ChatGPT 안에서 즉시 결제 같은 기능이 가능해질 수 있습니다. 프리미엄 기능이 있는 앱이라면 네이티브 결제 방법이 생길 수 있다는 뜻이죠.
더 넓게 보면 MCP 생태계에 주목할 필요가 있습니다. MCP는 오픈 스탠다드이므로, 만든 도구가 ChatGPT뿐 아니라 다른 AI 클라이언트에서도 작동할 수 있습니다. Anthropic의 Claude도 MCP를 지원하니까요. 단일 구현으로 여러 AI 플랫폼의 사용자에게 도달할 기회가 있습니다.
초기 플랫폼이라는 것은 험난한 개발 환경을 의미하지만, 동시에 가치 있는 것을 만들 여지가 많다는 뜻이기도 합니다. 새벽 2시 CORS 에러와 씨름할 준비가 되어 있다면요.
참고자료:
답글 남기기