MCP Joke Button App

This project is a tiny MCP server that exposes one MCP App UI: a single button. When the button is clicked, the app sends a message to the host asking the assistant to answer with one short, family-friendly joke.

It intentionally uses only Node.js built-in modules. There are no runtime package dependencies.

What It Demonstrates

• MCP core protocol version 2026-07-28
• Stateless Streamable HTTP on one endpoint: /mcp
• server/discover, tools/list, tools/call, resources/list, and resources/read
• MCP Apps UI resource metadata with _meta.ui.resourceUri
• A sandbox-friendly text/html;profile=mcp-app widget
• ui/initialize and ui/message over postMessage

Requirements

Install Node.js 20 or newer from nodejs.org. The LTS download is fine.

You do not need to run npm install; this project has no third-party libraries.

Start the Server

Open a terminal in this folder and run:

npm start

You should see:

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

Leave that terminal open while you test.

MCP requests are logged by method while the server is running. For an interactive app render, the log should include a successful UI resource read similar to:

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

Set MCP_LOG_REQUESTS=false if you want to disable these development logs.

Heroku Deployment

The joke-button Heroku app is deployed at:

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

Its MCP endpoint is:

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

Deploy the current branch with:

git push heroku HEAD:main

Quick Local Check

Open this address in a browser:

http://127.0.0.1:8787/preview

This only previews the button's appearance. The button can ask the AI for a joke only when it is rendered inside an MCP Apps-compatible host such as ChatGPT.

Use with ChatGPT Desktop or ChatGPT Web

ChatGPT needs an HTTPS URL for a remote MCP server during development. Keep npm start running, then expose port 8787 with a tunnel tool such as ngrok or Cloudflare Tunnel.

Example with ngrok:

ngrok http 8787

Copy the HTTPS forwarding URL and add /mcp to the end, for example:

https://example.ngrok.app/mcp

Then connect it in ChatGPT:

1. Open ChatGPT.
2. Open Settings.
3. Open Security and login.
4. Turn on Developer mode if it is not already enabled.
5. Open Plugins. If you are in the desktop app and do not see it in the sidebar, open https://chatgpt.com/plugins in a browser while signed in to the same account.
6. Select the plus button to add a developer MCP server connection.
7. Paste the HTTPS URL ending in /mcp.
8. Name it Joke Button.
9. Start a new chat, select the plugin from the More menu, and ask: Show the joke button.
10. Click Tell a joke.

You do not need a setting named MCP servers for this ChatGPT UI test. That setting is for Codex's local MCP host configuration, not for adding a ChatGPT developer plugin connection.

If Developer mode or the plus button is missing, check that the desktop app is up to date and that your account or workspace allows plugin development.

If the app is working, ChatGPT should receive the button's message and respond with a short joke.

Use with Codex in the ChatGPT Desktop App

Codex can connect to Streamable HTTP MCP servers from the shared MCP settings.

The MCP servers setting appears only on Codex-capable local clients and may not appear in a regular ChatGPT chat settings view. If it is available:

1. Keep npm start running.
2. Open the ChatGPT desktop app.
3. Open Settings, then MCP servers.
4. Select Add server.
5. Choose Streamable HTTP.
6. Name the server joke_button.
7. Use this URL:

http://127.0.0.1:8787/mcp

8. Save, then restart when prompted.
9. In a Codex task, type /mcp to confirm the server is connected.
10. Ask Codex: Use the Joke Button MCP server.

Codex MCP tool support may show the text fallback rather than rendering the iframe UI, depending on the surface. For the actual one-button UI, use ChatGPT with MCP Apps UI support.

If the setting is not visible, copy the sample configuration from codex-config.example.toml into a trusted project's .codex/config.toml or into your user ~/.codex/config.toml, then restart the ChatGPT desktop app or Codex client.

Useful URLs

• Health check: http://127.0.0.1:8787/health
• MCP endpoint: http://127.0.0.1:8787/mcp
• Widget preview: http://127.0.0.1:8787/preview

Security Notes

The server validates the MCP protocol version and mirrored MCP headers required by the 2026-07-28 Streamable HTTP transport.

For local development, requests without an Origin header are accepted, loopback browser origins are accepted, and common OpenAI host origins are accepted. For another host origin, start the server with:

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

Use authentication before exposing a real MCP server that can access private data or perform actions. This sample does neither.

Project Files

• server.js: dependency-free MCP server
• public/joke-button.html: MCP App UI widget
• codex-config.example.toml: sample Codex MCP configuration