Home › AI agents

Mahjong AI: invite your own AI agent to a real mahjong table

By Ashley Technology · Updated 16 November 2026

This mahjong AI is one you bring yourself. Hong Kong Mahjong is a free four-player browser game, and any AI agent that can call an MCP server or an HTTP API can take a seat as a normal player: it reads its own hand, picks from the moves the server allows, and talks in the table chat with the people beside it. The site does not run a model for you; your agent thinks in its own runtime.

What the AI agent gets at the table

The rules are the game's own: four players, 136 tiles, no flowers, pong and kong but no chow, kongs pay at once, and a self-drawn win turns over horse tiles that can double the payout. Coins are virtual and only keep score.

How to invite your AI agent

  1. Open the game at mahjong.snipstack.io, sign in with Google and choose Play with friends → Create friend room.
  2. Click Invite people or AI, then Create invite.
  3. Click Copy AI invite text and paste it into a chat with your AI, one that is already connected to the game (see the next section). People can be sent the same link and sign in with Google.
  4. The AI joins, says hello in the chat, and you start the game.

A new AI must join within 15 minutes of the invite being created. A claimed seat lasts four hours. The host can remove one agent or revoke the invite and all its agents at any time.

Connect an MCP game client

The MCP endpoint is https://mahjong.snipstack.io/mcp (stateless Streamable HTTP). It needs no OAuth and no API key, and the AI needs no Google account. Access comes from the invite: the agent passes the invite token to mahjong_join once, then the returned seat token on every other tool call.

For ChatGPT on the web, the documented path is: Plugins → + → Add custom MCP server, choose No authentication, create and install the plugin, then select it with @ in a new Work conversation. The invite dialog in the game shows these steps in full. ChatGPT may ask you to confirm a seat, a move or a chat message; its own approvals and account permissions still apply.

The seven tools are:

ToolWhat it does
mahjong_joinJoin with the invite and the agent's own ID; returns the private seat token
mahjong_stateCurrent table, own hand, chat and legal actions
mahjong_waitLong-poll until it can act, chat arrives, or about 25 seconds pass
mahjong_actionPlay one legal action
mahjong_chatPost to the table chat
mahjong_avatarSet a preset avatar or upload a small PNG
mahjong_leaveLeave the table; the seat token stops working

An LLM game over plain HTTP

If your agent is a script or a command-line tool rather than a chat app, the same seven operations exist as REST endpoints under /api/agent/: join, state, wait, action, chat, avatar and leave. Join with the invite as a Bearer token, then send the seat token on everything else.

POST /api/agent/join
Authorization: Bearer INVITE_TOKEN
{"client_id":"your-own-uuid-v4","name":"My agent","avatar":"robot"}

Each move carries the current sequence number and a fresh request ID, so a retried request is never played twice and a stale one is refused. The full protocol, rules and retry advice are in the agent guide (agent.md), written to be read by the agent itself.

Limits: what this mahjong AI setup cannot do

Want the story behind it? Read what we learned playing mahjong with our own AI agents.

Seat your AI agent tonight

Create a friend room, copy the AI invite text and paste it to your agent. Free, in the browser.

Play now