Tic-tac-toe against the model

A complete app that runs inside ChatGPT (and Claude): an MCP server in Python plus a React widget that the chat app draws in a sandboxed iframe. You tap the board, the model answers with its move, and the board updates.

About 800 lines in three files:

How it works

 ChatGPT app                                       main.py
 +-------------------------------+                 +---------------------------+
 | model ------------------------+-- tools/call -->| tictactoe_start / _move   |
 | iframe: React widget          |<-resources/read-| widget.html (Vite build)  |
 |   tap -- callTool ------------+-- tools/call -->| tictactoe_play / _state   |
 |   "your move" -- sendFollowUpMessage --> model  | GAMES{} = the real board  |
 +-------------------------------+                 +---------------------------+

1. Tools with _meta. tictactoe_start carries openai/outputTemplate: ui://widget/tictactoe.html, so ChatGPT draws the widget. tictactoe_play and tictactoe_state are openai/visibility: private: only the widget can call them, so only a tap can place an X.

2. The widget ships as one string. Vite + vite-plugin-singlefile builds React and the CSS into one ~160 KB HTML file, returned by resources/read as text/html+skybridge.

3. One tool result, three readers. content is text for the model (ending in "Your move: call tictactoe_move…"), structuredContent is JSON for the widget, _meta is for the host.

4. The loop. A tap calls tictactoe_play, then sendFollowUpMessage("I played X in cell 5 … your move") starts a model turn. The model calls tictactoe_move, and the widget polls tictactoe_state every 1.2 s until the O appears (servers can't push to widgets).

5. The server owns the board. It checks turns, rejects taken cells and decides wins. The widget reloads the board from the server on every mount, because ChatGPT can re-create a widget and hand it a stale result.

TTT_HOST=chatgpt advertises the Apps SDK metadata; TTT_HOST=claude advertises MCP Apps metadata (_meta.ui.resourceUri, text/html;profile=mcp-app). Same image, same widget.

Related MCP server: Chess MCP Server

Run it

cp .env.example .env          # set PUBLIC_HOST
docker compose up -d --build  # ChatGPT server on 127.0.0.1:8094, Claude on :8093

ChatGPT and Claude need a public HTTPS URL: put nginx (see nginx/ttt.conf.example), a tunnel such as ngrok, or any reverse proxy in front.

Widget development without Docker:

cd web && npm install && npm run build   # writes web/dist/index.html
cp dist/index.html ../widget.html
cd .. && pip install -r requirements.txt && uvicorn main:app --port 8000

Add it to ChatGPT

1. chatgpt.com → Settings → Apps & Connectors → Advanced → turn on Developer mode (paid plans). On a phone, first choose Request Desktop Website in Safari ("aA") or Chrome (⋯).

2. Create: any name, URL https://<your-host>/ttt/mcp, No authentication, tick "I trust" → Create.

3. In a chat: @Tic-tac-toe let's play, then tap a square.

ChatGPT caches the tool list and widget when the connector is created: after any change, delete the connector and add it again.

Try the live one: https://api.palomaressoftware.com/ttt/mcp (ChatGPT) or https://api.palomaressoftware.com/ttt-claude/mcp (Claude).

Known differences between hosts

• ChatGPT plays hands-free: sendFollowUpMessage starts a model turn after each tap.

• Claude (MCP Apps, tested on iOS): ui/message doesn't start a model turn, so you type "your move" after each tap. The widget asks you to after 6 s.

• In voice mode the model may announce a move without calling the tool; the tool descriptions forbid it, and only the server's board counts.

Tracing (optional)

tracing.py prints one JSON line per request (method, tool, timing, trace id) and a game event per move. Set SPLUNK_HEC_URL and SPLUNK_HEC_TOKEN to also send them to Splunk. It logs ids and timings only.

License

MIT