MCP Joke Button App

이 프로젝트는 단일 버튼이라는 하나의 MCP App UI를 노출하는 작은 MCP 서버입니다. 버튼을 클릭하면 앱이 호스트에 메시지를 보내 어시스턴트가 짧고 가족이 봐도 무해한 농담 하나로 답하도록 요청합니다.

의도적으로 Node.js 기본 모듈만 사용합니다. 런타임 패키지 의존성이 없습니다.

데모 내용

• MCP 핵심 프로토콜 버전 2026-07-28

• 단일 엔드포인트 /mcp에서의 Stateless Streamable HTTP

• server/discover, tools/list, tools/call, resources/list, resources/read

• _meta.ui.resourceUri를 사용한 MCP Apps UI 리소스 메타데이터

• 샌드박스 친화적인 text/html;profile=mcp-app 위젯

• postMessage를 통한 ui/initialize 및 ui/message

Related MCP server: Jokes MCP Server

요구 사항

nodejs.org에서 Node.js 20 이상을 설치하세요. LTS 다운로드로 충분합니다.

npm install을 실행할 필요가 없습니다. 이 프로젝트에는 타사 라이브러리가 없습니다.

서버 시작

이 폴더에서 터미널을 열고 다음을 실행하세요:

npm start

다음이 표시되어야 합니다:

MCP Joke Button server listening on http://127.0.0.1:8787/mcp
Preview the widget shell at http://127.0.0.1:8787/preview

테스트하는 동안 해당 터미널을 열어 두세요.

서버가 실행되는 동안 MCP 요청이 메서드별로 기록됩니다. 대화형 앱 렌더링의 경우 로그에 다음과 유사한 UI 리소스 읽기 성공 항목이 포함되어야 합니다:

[mcp] request method=resources/read name=ui://joke-button/app.html
[mcp] response method=resources/read status=200

개발 로그를 비활성화하려면 MCP_LOG_REQUESTS=false로 설정하세요.

Heroku 배포

joke-button Heroku 앱이 다음에 배포되어 있습니다:

https://joke-button-31cddc4bc964.herokuapp.com

MCP 엔드포인트는 다음과 같습니다:

https://joke-button-31cddc4bc964.herokuapp.com/mcp

다음 명령으로 현재 브랜치를 배포하세요:

git push heroku HEAD:main

빠른 로컬 확인

브라우저에서 이 주소를 여세요:

http://127.0.0.1:8787/preview

이것은 버튼의 모양만 미리 봅니다. 버튼은 ChatGPT와 같은 MCP Apps 호환 호스트 내에서 렌더링될 때만 AI에게 농담을 요청할 수 있습니다.

ChatGPT 데스크톱 또는 ChatGPT 웹에서 사용

ChatGPT는 개발 중에 원격 MCP 서버용 HTTPS URL이 필요합니다. npm start를 계속 실행한 상태에서 ngrok이나 Cloudflare Tunnel 같은 터널 도구로 포트 8787을 노출하세요.

ngrok 사용 예:

ngrok http 8787

HTTPS 전달 URL을 복사하고 끝에 /mcp를 추가하세요. 예:

https://example.ngrok.app/mcp

그런 다음 ChatGPT에서 연결하세요:

1. ChatGPT를 엽니다.

2. 설정을 엽니다.

3. 보안 및 로그인을 엽니다.

4. 개발자 모드가 아직 활성화되어 있지 않으면 켭니다.

5. 플러그인을 엽니다. 데스크톱 앱에서 사이드바에 보이지 않으면 같은 계정으로 로그인한 상태에서 브라우저에서 https://chatgpt.com/plugins를 엽니다.

6. 개발자 MCP 서버 연결을 추가하려면 더하기 버튼을 선택합니다.

7. /mcp로 끝나는 HTTPS URL을 붙여넣습니다.

8. 이름을 Joke Button으로 지정합니다.

9. 새 채팅을 시작하고 More 메뉴에서 플러그인을 선택한 다음 Show the joke button.이라고 요청합니다.

10. Tell a joke을 클릭합니다.

이 ChatGPT UI 테스트에는 MCP servers라는 설정이 필요하지 않습니다. 해당 설정은 ChatGPT 개발자 플러그인 연결을 추가하기 위한 것이 아니라 Codex의 로컬 MCP 호스트 구성을 위한 것입니다.

개발자 모드나 더하기 버튼이 보이지 않으면 데스크톱 앱이 최신 상태인지, 계정이나 워크스페이스에서 플러그인 개발을 허용하는지 확인하세요.

앱이 작동 중이면 ChatGPT가 버튼의 메시지를 받아 짧은 농담으로 응답해야 합니다.

ChatGPT 데스크톱 앱에서 Codex와 함께 사용

Codex는 공유 MCP 설정에서 Streamable HTTP MCP 서버에 연결할 수 있습니다.

MCP servers 설정은 Codex를 지원하는 로컬 클라이언트에서만 나타나며 일반 ChatGPT 채팅 설정 보기에는 표시되지 않을 수 있습니다. 사용 가능한 경우:

1. npm start를 계속 실행합니다.

2. ChatGPT 데스크톱 앱을 엽니다.

3. 설정을 연 다음 MCP servers를 엽니다.

4. Add server를 선택합니다.

5. Streamable HTTP를 선택합니다.

6. 서버 이름을 joke_button으로 지정합니다.

7. 이 URL을 사용합니다:

http://127.0.0.1:8787/mcp

8. 저장한 다음 메시지가 표시되면 다시 시작합니다.

9. Codex 작업에서 /mcp를 입력하여 서버가 연결되었는지 확인합니다.

10. Codex에 Use the Joke Button MCP server.라고 요청합니다.

Codex MCP 도구 지원은 표면에 따라 iframe UI를 렌더링하는 대신 텍스트 폴백을 표시할 수 있습니다. 실제 원버튼 UI를 보려면 MCP Apps UI를 지원하는 ChatGPT를 사용하세요.

설정이 보이지 않으면 codex-config.example.toml의 샘플 구성을 신뢰할 수 있는 프로젝트의 .codex/config.toml 또는 사용자 ~/.codex/config.toml에 복사한 다음 ChatGPT 데스크톱 앱이나 Codex 클라이언트를 다시 시작하세요.

유용한 URL

• 상태 확인: http://127.0.0.1:8787/health

• MCP 엔드포인트: http://127.0.0.1:8787/mcp

• 위젯 미리 보기: http://127.0.0.1:8787/preview

보안 참고 사항

서버는 2026-07-28 Streamable HTTP 전송에 필요한 MCP 프로토콜 버전과 미러링된 MCP 헤더를 검증합니다.

로컬 개발의 경우 Origin 헤더가 없는 요청, 루프백 브라우저 출처, 일반적인 OpenAI 호스트 출처가 허용됩니다. 다른 호스트 출처의 경우 다음으로 서버를 시작하세요:

$env:MCP_ALLOWED_ORIGINS="https://your-host.example"
npm start

개인 데이터에 접근하거나 작업을 수행할 수 있는 실제 MCP 서버를 노출하기 전에 인증을 사용하세요. 이 샘플은 둘 다 수행하지 않습니다.

프로젝트 파일

• server.js: 의존성 없는 MCP 서버

• public/joke-button.html: MCP App UI 위젯

• codex-config.example.toml: 샘플 Codex MCP 구성