ChatGPT Apps SDK 퀵스타트 오류해결 Quick Start Error Fix

ChatGPT Apps SDK로 내 서비스를 ChatGPT에 연결해보기: 베타 테스트 후기 & 퀵스타트 가이드

안녕하세요, Goosepeak입니다! 요즘 ChatGPT가 점점 똑똑해지면서, 내 서비스를 ChatGPT에 직접 연결하는 게 재미있겠다는 생각이 들었어요. OpenAI의 ChatGPT Apps SDK 베타를 써봤는데, 공식 문서대로 하면 앱 배포에서 500 오류가 나서 골치 아팠습니다. 디버깅 해보니 몇 가지 문제점이 있었고, 그걸 고쳐서 GitHub에 올렸어요. 관심 있으신 분들은 클론 받아서 테스트해보세요!

(링크: https://github.com/GoodPineApple/chatgpt-apps-sdk-quickstart)

GitHub - GoodPineApple/chatgpt-apps-sdk-quickstart

 

이 글에서는 이 프로젝트를 기반으로, ChatGPT에 MCP 서버를 이용해 Todo 앱 같은 커스텀 커넥터를 만드는 방법을 공유할게요. 저처럼 AI를 활용한 1인창업 아이디어 찾는 분들에게 유용할 거예요. 제가 직접 테스트하면서 느낀 팁도 섞어서 설명하겠습니다.

 

프로젝트 소개: 왜 이게 필요할까?

ChatGPT Apps SDK는 ChatGPT 안에서 내 앱을 동작하게 해주는 도구예요. 간단히 말해, ChatGPT가 내 서버와 소통하면서 기능을 호출할 수 있게 해줍니다. 공식 문서의 퀵스타트 예제는 Todo 앱을 만들라고 하죠. 그런데 그대로 따라 하면 커넥터 등록에서 실패해요. 이유는 HEAD 요청 미처리, Accept 헤더 무시, 요청 본문 스트림 처리 문제 때문입니다.

저는 이걸 고쳐서 실제로 작동하는 버전을 만들었어요. Google Cloud Run에 배포하고, ChatGPT Plus에서 개발자 모드로 테스트했죠. 결과? 완벽하게 동작! 제 프로젝트 중 EzDegree처럼, 학점 관리 서비스를 ChatGPT에 연결해볼 수 있을 것 같아요. 

학점은행제가 궁금할 땐? 이지디그리 | EzDegree

 

 

주요 개선사항: 공식 문서의 함정 피하기

공식 예제는 좋지만, 실제로 해보니 앱 생성파트에서 빙빙 돌기만하고 결국 안되는 오류가 있어요. 제가 디버깅하면서 고친 부분들입니다. 각 항목에 간단 설명과 왜 중요한지 적어봤어요.

1. HEAD 요청 처리 추가

ChatGPT가 연결 테스트로 HEAD 요청을 보내는데, 이걸 무시하면 404 오류가 납니다. 저는 Health check와 MCP 엔드포인트에서 HEAD를 지원하도록 수정했어요. 간단하지만, 이게 없으면 앱 등록이 막히죠.

2. Accept 헤더 기반 응답 형식 결정

ChatGPT는 요청에 따라 JSON이나 SSE(서버-센트 이벤트)를 기대해요.

• accept: application/json → JSON으로 응답
• accept: text/event-stream → SSE 스트리밍으로 응답
  enableJsonResponse 옵션을 동적으로 설정하니 문제가 풀렸습니다. 저는 처음에 이걸 몰라서 한참 헤맸어요.

3. 요청 본문 스트림 처리 개선

Node.js에서 HTTP 스트림은 한 번만 읽을 수 있어요. 요청 본문을 미리 읽으면 transport가 못 읽죠. 그래서 본문을 미리 건드리지 않고 transport가 직접 처리하도록 바꿨습니다.

4. 상세한 로깅 추가

디버깅이 핵심! 요청 ID, User-Agent, 헤더, 응답 시간 등을 로그로 남겼어요. Cloud Run 로그 보면 ChatGPT 요청이 제대로 오는지 바로 알 수 있습니다.

이 개선으로 공식 문서의 실패율을 0으로 만들었어요. 저는 이렇게 생각해요: OpenAI 문서는 좋지만, 베타라서 실전 팁이 부족한 것 같아요.

프로젝트 구조: 간단하게 파악하기

프로젝트는 이렇게 구성됐어요. 클론 받으면 바로 볼 수 있죠.

chatgpt-apps-sdk-quickstart/
├── public/
│   └── todo-widget.html    # ChatGPT에 보일 UI 컴포넌트
├── server.js               # MCP 서버 핵심 파일
├── package.json
├── app.yaml                # Google App Engine 설정
├── Dockerfile              # Cloud Run 배포용
└── README.md

Todo-widget.html은 ChatGPT 인터페이스에 iframe으로 렌더링되는 HTML이에요. 간단한 웹 컴포넌트죠.

빠른 시작: 따라 해보기

이제 실제로 해보죠. 단계별로 설명할게요. 저는 Mac에서 테스트했는데, Windows도 비슷할 거예요.

1. 의존성 설치

터미널 열고:

npm install

2. 로컬 실행

서버 띄우기:

npm start

http://localhost:8787/mcp 에서 확인하세요.

3. 배포 (Google Cloud Run 추천)

Google Cloud SDK 설치하고:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

gcloud run deploy chatgpt-apps-sdk \
  --source . \
  --platform managed \
  --region asia-northeast3 \
  --allow-unauthenticated \
  --port 8080

배포 URL: https://YOUR_SERVICE-XXXXX-xx.a.run.app/mcp

4. ChatGPT에 연결

• ChatGPT Plus 구독 필수예요.
• 설정 → Beta features에서 Developer mode 켜기.
• Connectors → Create에서 URL 입력 (위 배포 URL + /mcp).
• 인증: "인증없음" 선택.
• 새 채팅에서 "Show my tasks" 입력해보세요. Todo 리스트가 뜹니다!

핵심 개념: 이해하기 쉽게

MCP 서버 (Model Context Protocol)

ChatGPT와 앱이 소통하는 프로토콜이에요. Tools로 기능 정의 (예: add_todo), Resources로 UI 제공 (todo-widget.html).

웹 컴포넌트

ChatGPT 안에서 보이는 HTML. window.openai.callTool()로 도구 호출, window.openai.toolOutput으로 결과 읽기.

동작 흐름

사용자: "할 일 추가해줘"
→ ChatGPT: POST /mcp로 add_todo 호출
→ 서버: 처리 후 structuredContent 반환
→ ChatGPT: todo-widget.html 렌더링
→ 위젯: 데이터 표시

주요 코드: 직접 봐보세요

MCP 서버 설정 예시:

// Tools 등록
server.registerTool("add_todo", {
  title: "Add todo",
  description: "Creates a todo item with the given title.",
  inputSchema: { title: z.string().min(1) },
  _meta: {
    "openai/outputTemplate": "ui://widget/todo.html",
  },
}, async (args) => {
  // 도구 실행 로직
  return {
    content: [{ type: "text", text: "Added todo" }],
    structuredContent: { tasks: todos },
  };
});

// Resources 등록
server.registerResource("todo-widget", "ui://widget/todo.html", {}, async () => ({
  contents: [{
    uri: "ui://widget/todo.html",
    mimeType: "text/html+skybridge",
    text: todoHtml,
  }],
}));

HTTP 서버 설정:

const wantsSSE = acceptHeader.includes("text/event-stream");
const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
  enableJsonResponse: !wantsSSE,
});

문제 해결 팁: 오류 날 때

• 커넥터 등록 실패: HEAD 요청 확인, URL에 /mcp 포함, HTTPS 필수.
• 400 오류: 본문 스트림 안 건드리기, Content-Type 맞추기.
• SSE 문제: Accept 헤더 확인, enableJsonResponse false로.

직접 테스트해봐야 할 것 같아요. 저는 Cloud Run 로그가 큰 도움이 됐어요.

 

참고 자료

• OpenAI Apps SDK 공식 문서
• MCP 프로토콜 문서

마무르기: AI 미래를 향해!

이 프로젝트로 ChatGPT에 내 서비스를 쉽게 연결할 수 있어요. 저처럼 사이드 프로젝트 하시는 분들, 1인창업 관심 있으신 분들은 새로운 시장을 미리 준비해보시죠. 오류가 날 수 있으니, GitHub 이슈에 피드백 주시면 확인해보겠습니다.